uarite 0.1.0__tar.gz

uarite-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+.*
+!.gitignore
+*.lock

uarite-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: uarite
+Version: 0.1.0
+Summary: Compact, human-readable User-Agent formatting and bot detection — no regex database, stdlib only
+Project-URL: Repository, https://git.zi.fi/LeoVasanko/uarite
+Project-URL: Issues, https://github.com/LeoVasanko/uarite
+Author: Leo Vasanko
+Keywords: ua-parser,user-agent
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# uarite
+
+User-Agent parsing in Python has a long lineage. ua-parser is the official Python implementation of the ua-parser project, built around uap-core: the regex database extracted from BrowserScope's original parser and shared by implementations in many languages. user-agents wraps ua-parser with higher-level device and capability detection; its last release was in 2020. user-agent-parser is a separate implementation first released in 2022 and substantially updated in 2026, taking its own approach rather than building on uap-core. None of the three has further dependencies, but the regex databases weigh something: ua-parser installs at about 499 KB (531 KB with user-agents on top), user-agent-parser at 166 KB.
+
+```sh
+uv add uarite
+```
+
+This module is another take on the same problem: a small, dependency-free, compact pure-Python parser — 29 KB installed. It returns structured classifications, but also the thing most applications eventually need: a short human-readable description.
+
+It is particularly aimed at server-side analytics, where correctly recognizing crawlers and modern reduced User-Agents matters. It detects disguised crawlers, distinguishes AI/search/preview traffic, handles HarmonyOS and bots without calling them Android, resolves common device model codes and falls back to reasonable output even when all else fails.
+
+## Usage
+
+```python
+from uarite import uaparse
+
+r = uaparse("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36")
+
+r.pretty    # "Chrome/152 Windows"
+r.kind      # "browser"
+r.bot       # ""
+r.url       # ""
+
+r = uaparse("Mozilla/5.0 (Linux; Android 13; Pixel 7) ... Chrome/134.0.6885.65 "
+            "Mobile Safari/537.36; compatible; facebookexternalhit/1.1; "
+            "+http://www.facebook.com/externalhit_uatext.php")
+
+r.pretty    # "Facebook"
+r.kind      # "preview"
+r.bot       # "Facebook"
+r.url       # "http://www.facebook.com/externalhit_uatext.php"
+```
+
+## Output
+
+`uaparse(ua)` returns a frozen `UA` dataclass:
+
+| Field    | Content                                                                                          |
+| -------- | ------------------------------------------------------------------------------------------------ |
+| `pretty` | Compact display string (below); `""` for empty/missing UAs, the raw UA when unrecognized         |
+| `bot`    | Crawler/previewer display name, or `""`                                                          |
+| `kind`   | `"browser"`, `"ai"`, `"search"`, `"preview"`, `"spider"`, or `""` (scripts/HTTP libraries)       |
+| `url`    | The crawler's info URL (`+https://…` pointer), or `""`; not part of `pretty` — link it in the UI |
+
+`kind` is `"browser"` for Mozilla-format UAs with no bot token, `"ai"` for training-data and AI-assistant fetchers (GPTBot, ClaudeBot, Google-Extended, ...), `"search"` for search-engine indexing (Googlebot, Bingbot, ...), `"preview"` for social link-preview fetchers (Facebook, WhatsApp, Slack, ...), `"spider"` for generic or unknown crawlers, and `""` for scripts and HTTP libraries.
+
+`pretty` is intended to be shown directly:
+
+- Desktop: `Chrome/152 Windows`, `Safari/18 macOS`
+- iPhone/iPad: `iPhone iOS 17` — the device and iOS version, not Safari (the only browser iOS has)
+- Android: `Chrome/118 Pixel 6`, or `Chrome/152 Android` when the device is unknown
+- Crawlers: `GPTBot (AI)`, `Googlebot (search)`, `Facebook` — the kind suffix appears only where a provider runs crawlers of more than one kind; single-kind providers stay plain
+- Scripts: `python-requests/2.32.5`, `pip/24.3.1 Linux`
+
+Chrome's reduced Android UA reports the frozen values `Android 10; K`; neither is real device information, so uarite deliberately reports simply `Android`. HarmonyOS compatibility strings are similarly recognized before their misleading Android tokens.
+
+## Performance
+
+All compared parsers cache repeated User-Agents, making cache hits effectively free. The useful difference is therefore the first parse of a new string.
+
+In our benchmarks, uncached uarite parses take roughly **3–7 µs**. user-agent-parser is in the same general range at **~7 µs**, while the pure-Python ua-parser/user-agents path takes roughly **130–250 µs**.
+
+The cache strategies differ in ways that matter under adversarial traffic. uarite caches only browser/client results (1024-entry LRU): crawlers tend to be unique and would otherwise evict the repeating UAs where caching is useful. user-agent-parser's 512-entry LRU lets a bot storm evict browsers, and user-agents' 200-entry dict clears entirely when full.
+
+## Accuracy
+
+The main difference is not how many fields can be returned, but what the parser believes the User-Agent actually says.
+
+For example, reduced Chrome does not really tell us that the device is named `K` or that it runs Android 10; an Android compatibility token does not make HarmonyOS Android; and a Facebook or Google crawler containing a plausible Chrome UA is still a crawler, not a Chrome visitor.
+
+The table below compares representative results. uarite shows `r.pretty`; the ua-parser display strings are assembled from its structured output for comparison. user-agents is omitted: it shares the ua-parser backend and returns virtually identical data in a slightly different structure.
+
+| Case                         | uarite¹                   | ua-parser²                                    |
+| ---------------------------- | ------------------------- | --------------------------------------------- |
+| Chrome, Windows              | Chrome/152 Windows        | Chrome/152 Windows                            |
+| Safari, macOS                | Safari/18 macOS           | Safari/18 Mac OS X Mac                        |
+| Opera, Linux                 | Opera/106 Linux           | Opera/106 Linux                               |
+| Chrome, Android (no model)   | Chrome/152 Android        | Chrome Mobile/152 Android K❌                 |
+| Chrome, Android (Pixel)      | Chrome/118 Pixel 6        | Chrome Mobile/118 Android Pixel 6             |
+| Edge, Android (model code)   | Edge/110 Galaxy S7        | Edge Mobile/110 Android Samsung SM-G930P      |
+| Firefox, Android             | Firefox/154 Android 15    | Firefox Mobile/154 Android Generic Smartphone |
+| Safari, iPhone               | iPhone iOS 17             | Mobile Safari/17 iOS iPhone                   |
+| Huawei HarmonyOS phone       | HuaweiBrowser/6 HarmonyOS | Huawei Browser/6 Android❌ Huawei Browser     |
+| GPTBot                       | GPTBot (AI)               | GPTBot/1 Spider                               |
+| Googlebot (disguised)        | Googlebot (search)        | Googlebot/2 Android❌ Spider                  |
+| Facebook preview (disguised) | Facebook                  | FacebookBot/1 Android Pixel 7 ❌              |
+| Meta crawler (disguised)     | Meta                      | Chrome/145 Windows ❌                         |
+| WhatsApp preview             | WhatsApp                  | WhatsApp/10 Spider                            |
+| Bytespider                   | Bytespider                | Bytespider/ Android❌ Generic Smartphone      |
+| BingPreview                  | BingPreview (preview)     | BingPreview/1 Windows❌ Spider                |
+| AhrefsBot                    | AhrefsBot                 | AhrefsBot/7 Spider                            |
+| python-requests              | python-requests/2.32.5    | Python Requests/2                             |
+
+❌ marks an incorrect browser, OS, or device interpretation.
+¹ `r.pretty` shown as is
+² `{user_agent.family}/{user_agent.major} {os.family} {device.family}`
+
+Measured on 100 current browser UAs, family / version / OS accuracy is 80% / 91% / 99% for both ua-parser and user-agents, and 90% / 90% / 100% for uarite — its nominal "misses" are the iPhone rows, where it reports `iPhone iOS 17` rather than Mobile Safari, a deliberate choice since Safari is the only browser iOS has. user-agent-parser is absent from the table: it detected under a third of the crawlers in the test below and crashed on five inputs, so a side-by-side formatting comparison adds little.
+
+Crawler detection was also tested against 2163 real-world crawler UAs from [monperrus/crawler-user-agents](https://github.com/monperrus/crawler-user-agents):
+
+| Parser            | Detected                 |
+| ----------------- | ------------------------ |
+| ua-parser         | 63.8%                    |
+| user-agents       | 60.1%                    |
+| user-agent-parser | 31.9% (crashed on 5 UAs) |
+| uarite            | 79.9%                    |
+
+The remaining uarite misses are mostly ancient tokenless crawler names and ordinary HTTP libraries, which are intentionally classified as scripts rather than bots.
+
+## Design
+
+uarite uses a small hand-maintained regex/rule database rather than the much larger uap-core dataset. Rules are kept simple enough to audit directly and ordered so that specific identities such as crawlers or HarmonyOS win over browser compatibility tokens. The generic tells are few: a product token containing bot/spider/crawl/scan/verify/check, or an info URL in the UA — real browsers never carry one.
+
+Unknown UAs remain visible: `pretty` falls back to the original string rather than discarding them, and malformed input never raises.
+
+Some information simply is not present in a User-Agent. Modern Brave is normally indistinguishable from Chrome without browser-side detection, and iPhone UAs do not contain the device model. uarite prefers an incomplete answer to an invented one.

uarite-0.1.0/README.md

@@ -0,0 +1,119 @@
+# uarite
+
+User-Agent parsing in Python has a long lineage. ua-parser is the official Python implementation of the ua-parser project, built around uap-core: the regex database extracted from BrowserScope's original parser and shared by implementations in many languages. user-agents wraps ua-parser with higher-level device and capability detection; its last release was in 2020. user-agent-parser is a separate implementation first released in 2022 and substantially updated in 2026, taking its own approach rather than building on uap-core. None of the three has further dependencies, but the regex databases weigh something: ua-parser installs at about 499 KB (531 KB with user-agents on top), user-agent-parser at 166 KB.
+
+```sh
+uv add uarite
+```
+
+This module is another take on the same problem: a small, dependency-free, compact pure-Python parser — 29 KB installed. It returns structured classifications, but also the thing most applications eventually need: a short human-readable description.
+
+It is particularly aimed at server-side analytics, where correctly recognizing crawlers and modern reduced User-Agents matters. It detects disguised crawlers, distinguishes AI/search/preview traffic, handles HarmonyOS and bots without calling them Android, resolves common device model codes and falls back to reasonable output even when all else fails.
+
+## Usage
+
+```python
+from uarite import uaparse
+
+r = uaparse("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36")
+
+r.pretty    # "Chrome/152 Windows"
+r.kind      # "browser"
+r.bot       # ""
+r.url       # ""
+
+r = uaparse("Mozilla/5.0 (Linux; Android 13; Pixel 7) ... Chrome/134.0.6885.65 "
+            "Mobile Safari/537.36; compatible; facebookexternalhit/1.1; "
+            "+http://www.facebook.com/externalhit_uatext.php")
+
+r.pretty    # "Facebook"
+r.kind      # "preview"
+r.bot       # "Facebook"
+r.url       # "http://www.facebook.com/externalhit_uatext.php"
+```
+
+## Output
+
+`uaparse(ua)` returns a frozen `UA` dataclass:
+
+| Field    | Content                                                                                          |
+| -------- | ------------------------------------------------------------------------------------------------ |
+| `pretty` | Compact display string (below); `""` for empty/missing UAs, the raw UA when unrecognized         |
+| `bot`    | Crawler/previewer display name, or `""`                                                          |
+| `kind`   | `"browser"`, `"ai"`, `"search"`, `"preview"`, `"spider"`, or `""` (scripts/HTTP libraries)       |
+| `url`    | The crawler's info URL (`+https://…` pointer), or `""`; not part of `pretty` — link it in the UI |
+
+`kind` is `"browser"` for Mozilla-format UAs with no bot token, `"ai"` for training-data and AI-assistant fetchers (GPTBot, ClaudeBot, Google-Extended, ...), `"search"` for search-engine indexing (Googlebot, Bingbot, ...), `"preview"` for social link-preview fetchers (Facebook, WhatsApp, Slack, ...), `"spider"` for generic or unknown crawlers, and `""` for scripts and HTTP libraries.
+
+`pretty` is intended to be shown directly:
+
+- Desktop: `Chrome/152 Windows`, `Safari/18 macOS`
+- iPhone/iPad: `iPhone iOS 17` — the device and iOS version, not Safari (the only browser iOS has)
+- Android: `Chrome/118 Pixel 6`, or `Chrome/152 Android` when the device is unknown
+- Crawlers: `GPTBot (AI)`, `Googlebot (search)`, `Facebook` — the kind suffix appears only where a provider runs crawlers of more than one kind; single-kind providers stay plain
+- Scripts: `python-requests/2.32.5`, `pip/24.3.1 Linux`
+
+Chrome's reduced Android UA reports the frozen values `Android 10; K`; neither is real device information, so uarite deliberately reports simply `Android`. HarmonyOS compatibility strings are similarly recognized before their misleading Android tokens.
+
+## Performance
+
+All compared parsers cache repeated User-Agents, making cache hits effectively free. The useful difference is therefore the first parse of a new string.
+
+In our benchmarks, uncached uarite parses take roughly **3–7 µs**. user-agent-parser is in the same general range at **~7 µs**, while the pure-Python ua-parser/user-agents path takes roughly **130–250 µs**.
+
+The cache strategies differ in ways that matter under adversarial traffic. uarite caches only browser/client results (1024-entry LRU): crawlers tend to be unique and would otherwise evict the repeating UAs where caching is useful. user-agent-parser's 512-entry LRU lets a bot storm evict browsers, and user-agents' 200-entry dict clears entirely when full.
+
+## Accuracy
+
+The main difference is not how many fields can be returned, but what the parser believes the User-Agent actually says.
+
+For example, reduced Chrome does not really tell us that the device is named `K` or that it runs Android 10; an Android compatibility token does not make HarmonyOS Android; and a Facebook or Google crawler containing a plausible Chrome UA is still a crawler, not a Chrome visitor.
+
+The table below compares representative results. uarite shows `r.pretty`; the ua-parser display strings are assembled from its structured output for comparison. user-agents is omitted: it shares the ua-parser backend and returns virtually identical data in a slightly different structure.
+
+| Case                         | uarite¹                   | ua-parser²                                    |
+| ---------------------------- | ------------------------- | --------------------------------------------- |
+| Chrome, Windows              | Chrome/152 Windows        | Chrome/152 Windows                            |
+| Safari, macOS                | Safari/18 macOS           | Safari/18 Mac OS X Mac                        |
+| Opera, Linux                 | Opera/106 Linux           | Opera/106 Linux                               |
+| Chrome, Android (no model)   | Chrome/152 Android        | Chrome Mobile/152 Android K❌                 |
+| Chrome, Android (Pixel)      | Chrome/118 Pixel 6        | Chrome Mobile/118 Android Pixel 6             |
+| Edge, Android (model code)   | Edge/110 Galaxy S7        | Edge Mobile/110 Android Samsung SM-G930P      |
+| Firefox, Android             | Firefox/154 Android 15    | Firefox Mobile/154 Android Generic Smartphone |
+| Safari, iPhone               | iPhone iOS 17             | Mobile Safari/17 iOS iPhone                   |
+| Huawei HarmonyOS phone       | HuaweiBrowser/6 HarmonyOS | Huawei Browser/6 Android❌ Huawei Browser     |
+| GPTBot                       | GPTBot (AI)               | GPTBot/1 Spider                               |
+| Googlebot (disguised)        | Googlebot (search)        | Googlebot/2 Android❌ Spider                  |
+| Facebook preview (disguised) | Facebook                  | FacebookBot/1 Android Pixel 7 ❌              |
+| Meta crawler (disguised)     | Meta                      | Chrome/145 Windows ❌                         |
+| WhatsApp preview             | WhatsApp                  | WhatsApp/10 Spider                            |
+| Bytespider                   | Bytespider                | Bytespider/ Android❌ Generic Smartphone      |
+| BingPreview                  | BingPreview (preview)     | BingPreview/1 Windows❌ Spider                |
+| AhrefsBot                    | AhrefsBot                 | AhrefsBot/7 Spider                            |
+| python-requests              | python-requests/2.32.5    | Python Requests/2                             |
+
+❌ marks an incorrect browser, OS, or device interpretation.
+¹ `r.pretty` shown as is
+² `{user_agent.family}/{user_agent.major} {os.family} {device.family}`
+
+Measured on 100 current browser UAs, family / version / OS accuracy is 80% / 91% / 99% for both ua-parser and user-agents, and 90% / 90% / 100% for uarite — its nominal "misses" are the iPhone rows, where it reports `iPhone iOS 17` rather than Mobile Safari, a deliberate choice since Safari is the only browser iOS has. user-agent-parser is absent from the table: it detected under a third of the crawlers in the test below and crashed on five inputs, so a side-by-side formatting comparison adds little.
+
+Crawler detection was also tested against 2163 real-world crawler UAs from [monperrus/crawler-user-agents](https://github.com/monperrus/crawler-user-agents):
+
+| Parser            | Detected                 |
+| ----------------- | ------------------------ |
+| ua-parser         | 63.8%                    |
+| user-agents       | 60.1%                    |
+| user-agent-parser | 31.9% (crashed on 5 UAs) |
+| uarite            | 79.9%                    |
+
+The remaining uarite misses are mostly ancient tokenless crawler names and ordinary HTTP libraries, which are intentionally classified as scripts rather than bots.
+
+## Design
+
+uarite uses a small hand-maintained regex/rule database rather than the much larger uap-core dataset. Rules are kept simple enough to audit directly and ordered so that specific identities such as crawlers or HarmonyOS win over browser compatibility tokens. The generic tells are few: a product token containing bot/spider/crawl/scan/verify/check, or an info URL in the UA — real browsers never carry one.
+
+Unknown UAs remain visible: `pretty` falls back to the original string rather than discarding them, and malformed input never raises.
+
+Some information simply is not present in a User-Agent. Modern Brave is normally indistinguishable from Chrome without browser-side detection, and iPhone UAs do not contain the device model. uarite prefers an incomplete answer to an invented one.

uarite-0.1.0/dist/.gitignore

@@ -0,0 +1 @@
+*

uarite-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = [
+    "hatchling>=1.25.0",
+    "hatch-vcs>=0.4.0",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "uarite"
+dynamic = ["version"]
+description = "Compact, human-readable User-Agent formatting and bot detection — no regex database, stdlib only"
+authors = [
+    { name = "Leo Vasanko" },
+]
+keywords = ["user-agent", "ua-parser"]
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://git.zi.fi/LeoVasanko/uarite"
+Issues = "https://github.com/LeoVasanko/uarite"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["uarite"]

uarite-0.1.0/scripts/README.md

@@ -0,0 +1,30 @@
+# Benchmark scripts
+
+Recreate every statistic and table quoted in the top-level README.
+`uarite` must be importable (e.g. `pip install -e .` or run with
+`PYTHONPATH` pointing at the repo root); the reference parsers are
+benchmark-only dependencies, pulled ad hoc via `uv run --with`.
+
+- `download_data.py` — fetch the external datasets into `data/`:
+  the 100 modern browser UAs (top-user-agents npm package) and the
+  crawler corpus (monperrus/crawler-user-agents). `data/ua.txt` is a
+  committed real-traffic sample, not downloaded.
+
+  ```
+  uv run scripts/download_data.py
+  ```
+
+- `prettytable.py` — prints the accuracy-comparison markdown table:
+
+  ```
+  uv run --with ua-parser --with user-agents python scripts/prettytable.py
+  ```
+
+- `bench.py` — prints browser-accuracy counts, crawler-detection rates,
+  URL-extraction coverage, and the timing tables (unique UAs, realistic
+  mix, bot storm) with cache statistics:
+
+  ```
+  uv run --with ua-parser --with user-agents --with user-agent-parser \
+      python scripts/bench.py
+  ```

uarite-0.1.0/scripts/bench.py

@@ -0,0 +1,277 @@
+"""Benchmark uarite vs ua-parser vs user-agents vs user-agent-parser.
+
+Reproduces the README's numbers: browser accuracy on 100 modern UAs,
+crawler detection on 2163 real-world crawler UAs, and timing (unique UAs,
+a realistic repeat/unique mix, a pure bot storm) with cache introspection.
+
+Data lives in scripts/data (see download_data.py).  Requires uarite
+(installed) plus the benchmark-only reference parsers:
+
+    uv run --with ua-parser --with user-agents --with user-agent-parser \
+        python scripts/bench.py
+"""
+
+import json
+import random
+import re
+import timeit
+from pathlib import Path
+
+from ua_parser import parse as ua_parse
+from user_agent_parser import parse as uap_parse
+from user_agents import parse as uas_parse
+
+from uarite import uaparse
+from uarite.core import _parse_client
+
+DATA = Path(__file__).parent / "data"
+BROWSERS = json.loads((DATA / "top-user-agents.json").read_text())
+CRAWLERS = json.loads((DATA / "crawler-user-agents.json").read_text())
+OWN = (DATA / "ua.txt").read_text().splitlines()
+CRAWLER_UAS = [ua for c in CRAWLERS for ua in (c.get("instances") or [c["pattern"]])]
+
+
+def expected(ua):
+    """De-facto ground truth for real-browser UAs: (family, major, os)."""
+    fam = major = ""
+    for tok, name in (
+        ("EdgA", "Edge"),
+        ("Edg", "Edge"),
+        ("OPR", "Opera"),
+        ("SamsungBrowser", "Samsung Internet"),
+        ("Firefox", "Firefox"),
+        ("Chrome", "Chrome"),
+    ):
+        m = re.search(re.escape(tok) + r"/(\d+)", ua)
+        if m:
+            fam, major = name, m.group(1)
+            break
+    if not fam and "Safari/" in ua:
+        m = re.search(r"Version/(\d+)", ua)
+        fam, major = "Safari", m.group(1) if m else ""
+    if not fam and ("iPhone" in ua or "iPad" in ua):
+        fam = "Safari"  # iOS webview UA: no browser token, Safari engine
+    if "iPhone" in ua or "iPad" in ua:
+        os = "ios"
+    elif re.search(r"Android [\d.]", ua):
+        os = "android"
+    elif "Windows NT" in ua:
+        os = "windows"
+    elif "Mac OS X" in ua:
+        os = "macos"
+    elif "Linux" in ua or "X11" in ua:
+        os = "linux"
+    else:
+        os = ""
+    return fam, major, os
+
+
+def norm_os(s):
+    s = (s or "").lower().replace(" ", "").replace("_", "")
+    return {"macosx": "macos", "ubuntu": "linux"}.get(s, s)
+
+
+def score_browsers():
+    res = {}
+    for name, fn in (
+        ("ua-parser", ua_parse),
+        ("user-agents", uas_parse),
+        ("user-agent-parser", uap_parse),
+    ):
+        fam_ok = ver_ok = os_ok = 0
+        for ua in BROWSERS:
+            efam, emaj, eos = expected(ua)
+            r = fn(ua)
+            if name == "ua-parser":
+                fam = r.user_agent.family or ""
+                maj = r.user_agent.major or ""
+                osf = r.os.family or ""
+            elif name == "user-agent-parser":
+                fam = r[0] or ""
+                maj = (r[1] or "").split(".")[0]
+                osf = r[2] or ""
+            else:
+                fam = r.browser.family or ""
+                maj = str(r.browser.version[0]) if r.browser.version else ""
+                osf = r.os.family or ""
+            fam = fam.split()[0]
+            fam_ok += efam.split()[0].lower() == fam.lower()
+            ver_ok += emaj == maj
+            os_ok += eos == norm_os(osf)
+        res[name] = (fam_ok, ver_ok, os_ok)
+    fam_ok = ver_ok = os_ok = 0
+    for ua in BROWSERS:
+        efam, emaj, eos = expected(ua)
+        r = uaparse(ua)
+        if emaj:
+            fam_ok += f"{efam}/{emaj}" in r.pretty
+            ver_ok += f"/{emaj}" in r.pretty
+        else:
+            # iOS webview: no version; "iPhone iOS 18" is the right answer
+            fam_ok += efam in r.pretty or "iPhone" in r.pretty or "iPad" in r.pretty
+            ver_ok += 1
+        oslabel = {
+            "ios": ("iPhone", "iPad"),
+            "macos": ("macOS",),
+            "windows": ("Windows",),
+            "linux": ("Linux",),
+            "android": ("Android",),
+        }.get(eos, ())
+        # Android with a known model drops the OS by design
+        model = re.search(r"Android [\d.]+; ([^;()]+?)(?:;|\))", ua)
+        has_model = eos == "android" and model and model.group(1) not in ("K", "Mobile")
+        os_ok += bool(any(os in r.pretty for os in oslabel) or has_model)
+    res["uarite"] = (fam_ok, ver_ok, os_ok)
+    return res
+
+
+def score_crawlers():
+    out = {}
+    crashes = 0
+    for name in ("ua-parser", "user-agents", "user-agent-parser", "uarite"):
+        det = 0
+        for ua in CRAWLER_UAS:
+            try:
+                if name == "ua-parser":
+                    r = ua_parse(ua)
+                    fam = r.user_agent.family if r.user_agent else ""
+                    bot = (r.device.family == "Spider" if r.device else False) or bool(
+                        re.search(r"bot|spider|crawl", fam, re.I)
+                    )
+                elif name == "user-agents":
+                    bot = uas_parse(ua).is_bot
+                elif name == "user-agent-parser":
+                    bot = uap_parse(ua)[4] == "Bot"
+                else:
+                    bot = bool(uaparse(ua).bot)
+            except Exception:
+                crashes += name == "user-agent-parser"
+                continue
+            det += bot
+        out[name] = det
+    url_have = sum(1 for ua in CRAWLER_UAS if re.search(r"https?://", ua))
+    url_got = sum(1 for ua in CRAWLER_UAS if uaparse(ua).url)
+    return out, url_have, url_got, crashes
+
+
+def realistic_mix():
+    """Realistic traffic: browsers repeat (weighted — popular combos many
+    times), interleaved with a steady stream of mostly-unique bot UAs that
+    hammer every parser's cache."""
+    rng = random.Random(42)
+    browsers = []
+    for i in range(2000):
+        # zipf-ish: early (popular) UAs repeat heavily
+        browsers.append(BROWSERS[int(100 * (rng.random() ** 3))])
+    bots = list(CRAWLER_UAS)
+    rng.shuffle(bots)
+    bots = bots[:1000]
+    # synthetic cache-busters: unique disguised bot UAs
+    for i in range(1000):
+        bots.append(
+            f"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            f" (KHTML, like Gecko) Chrome/{100 + i % 50}.0.{i}.0 Safari/537.36;"
+            f" compatible; ScrapeBot{i}/1.{i}; +http://scrapebot{i}.example.com/"
+        )
+    mix = [None] * (len(browsers) + len(bots))
+    mix[::2] = browsers
+    mix[1::2] = bots
+    return mix
+
+
+def bench_realistic():
+    mix = realistic_mix()
+    storm = [f"UniqueBot{i}/2.{i} (+http://ub{i}.example.com/)" for i in range(5000)]
+    print(
+        f"\n## realistic mix ({len(mix)} UAs: 2000 repeating browsers interleaved"
+        f" with 2000 mostly-unique bots)"
+    )
+    for name, fn in (
+        ("ua-parser", ua_parse),
+        ("user-agents", uas_parse),
+        ("user-agent-parser", uap_parse),
+        ("uarite", uaparse),
+    ):
+        fn = safe(fn)
+        t = timeit.timeit(lambda: [fn(u) for u in mix], number=1)
+        info = cache_info(name)
+        print(f"{name:20} {t / len(mix) * 1e6:7.1f} µs/UA   cache: {info}")
+    print(f"\n## pure bot storm ({len(storm)} unique UAs, zero cache value)")
+    for name, fn in (
+        ("ua-parser", ua_parse),
+        ("user-agents", uas_parse),
+        ("user-agent-parser", uap_parse),
+        ("uarite", uaparse),
+    ):
+        fn = safe(fn)
+        t = timeit.timeit(lambda: [fn(u) for u in storm], number=1)
+        print(
+            f"{name:20} {t / len(storm) * 1e6:7.1f} µs/UA   cache: {cache_info(name)}"
+        )
+
+
+def safe(fn):
+    def f(u):
+        try:
+            return fn(u)
+        except Exception:
+            return None
+
+    return f
+
+
+def cache_info(name):
+    if name == "uarite":
+        i = _parse_client.cache_info()
+        return f"{i.hits} hits / {i.misses} misses (cap 1024, browsers only)"
+    if name == "user-agent-parser":
+        from user_agent_parser.parser import _cached_parse_user_agent
+
+        i = _cached_parse_user_agent.cache_info()
+        return f"{i.hits} hits / {i.misses} misses (cap 512 LRU)"
+    if name == "user-agents":
+        from ua_parser.user_agent_parser import _PARSE_CACHE
+
+        return f"{len(_PARSE_CACHE)} entries (cap 200, CLEARS when full)"
+    if name == "ua-parser":
+        return "cap 2000 S3-FIFO (scan-resistant)"
+    return ""
+
+
+def bench():
+    alluas = BROWSERS + CRAWLER_UAS + OWN
+    n = 3
+    res = {}
+    for name, fn in (
+        ("ua-parser", ua_parse),
+        ("user-agents", uas_parse),
+        ("user-agent-parser", uap_parse),
+        ("uarite", uaparse),
+    ):
+        fn = safe(fn)
+        t = timeit.timeit(lambda: [fn(u) for u in alluas], number=n)
+        res[name] = t / n / len(alluas) * 1e6
+    # warm cache: repeat a small realistic working set many times
+    working = (BROWSERS + OWN[:50]) * 10
+    t = timeit.timeit(lambda: [uaparse(u) for u in working], number=n)
+    res["uarite (warm cache)"] = t / n / len(working) * 1e6
+    return res
+
+
+if __name__ == "__main__":
+    print(f"## browser accuracy (n={len(BROWSERS)}): family / version / OS correct")
+    for k, (f, v, o) in score_browsers().items():
+        print(f"{k:14} {f:3}/100   {v:3}/100   {o:3}/100")
+    det, url_have, url_got, crashes = score_crawlers()
+    print(f"\n## crawler detection (n={len(CRAWLER_UAS)})")
+    for k, v in det.items():
+        print(f"{k:18} {v:5}  ({v / len(CRAWLER_UAS):.1%})")
+    print(f"user-agent-parser crashed on {crashes} UAs")
+    print(f"\nuarite URL extraction: {url_got}/{url_have} of instances carrying a URL")
+    print(
+        "\n## speed (µs per parse, mixed set of %d UAs)"
+        % (len(BROWSERS) + len(CRAWLER_UAS) + len(OWN))
+    )
+    for k, v in bench().items():
+        print(f"{k:20} {v:8.1f}")
+    bench_realistic()