captcha-detector 1.0.0__tar.gz

captcha_detector-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScrapePass
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

captcha_detector-1.0.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: captcha-detector
+Version: 1.0.0
+Summary: Does this web page have a captcha? Detects 69 captcha and bot-check products (reCAPTCHA, hCaptcha, Turnstile, DataDome, PerimeterX...) in HTML, scraper API results, Playwright and Selenium. Zero dependencies.
+Author: ScrapePass
+License: MIT
+Project-URL: Homepage, https://github.com/ScrapePass/captcha-detector
+Project-URL: Source, https://github.com/ScrapePass/captcha-detector/tree/main/python
+Project-URL: Issues, https://github.com/ScrapePass/captcha-detector/issues
+Keywords: captcha,captcha-detection,recaptcha,hcaptcha,turnstile,cloudflare,bot-detection,web-scraping,playwright,selenium,datadome
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.30; extra == "playwright"
+Provides-Extra: selenium
+Requires-Dist: selenium>=4; extra == "selenium"
+Dynamic: license-file
+
+# captcha-detector for Python
+
+**Does this web page have a captcha?** The Python version of [captcha-detector](https://github.com/ScrapePass/captcha-detector): the same 69 named captcha and bot-check products plus catch-all rules, the same answers, zero dependencies.
+
+- **Check what your scraper got back:** pass a `requests`, `httpx`, `aiohttp`, `curl_cffi`, Scrapy or urllib response, or the JSON a scraper API sent, and find out whether you got the real page or a captcha, a bot check or a block page.
+- **Every kind:** checkbox widgets, invisible/score captchas, puzzles and sliders, proof-of-work, image captchas, math and text questions, full-page bot checks ("Just a moment…", "Press & Hold"), and access-denied pages.
+- **Real browsers too:** Playwright (sync and async) and Selenium, cross-origin frames included, with `visible` telling you whether the captcha is on screen.
+
+```bash
+pip install captcha-detector
+```
+
+## Check a response
+
+```python
+import requests
+from captcha_detector import detect_response
+
+url = "https://shop.example/product/42"
+res = requests.get(url)
+r = detect_response(res)
+
+if r.captcha or r.challenge_page or r.blocked:
+    print("Not the real page:", r.summary)   # e.g. "Captcha found: DataDome captcha (slider) [visible]"
+else:
+    parse(res.text)
+```
+
+`detect_response()` takes:
+
+| Input | Example |
+|---|---|
+| `requests` / `httpx` / `curl_cffi` / `niquests` response | `detect_response(requests.get(url))` |
+| Scrapy response | `detect_response(response)` inside `parse()` |
+| `urllib.request` / `urllib3` response | `detect_response(urlopen(url))` |
+| `aiohttp` response | `await detect_response_async(resp)` |
+| HTML as `str` or `bytes` | `detect_response(html, url=url)` |
+| A scraper API's JSON (`str`, `dict` or `list`) | `detect_response(api_res.json(), url=target)` |
+
+### Results from scraper APIs
+
+HTML wrapped in JSON (`{"html": …}`, `{"result": {"content": …}}` and the like) is found on its own, along with the status code, headers and URL next to it.
+
+```python
+target = "https://shop.example/product/42"
+res = requests.get("https://scraper-api.example/v1", params={"url": target, "key": KEY})
+r = detect_response(res, url=target)
+if r.captcha or r.challenge_page or r.blocked:
+    ...  # retry with another proxy or provider, don't parse or store this one
+```
+
+Pass `url`, the page you asked the API to scrape, not the API's own address. Most scraper APIs answer `200` whatever the site did; that's fine, the page itself gives a captcha away. If your API reports the site's real status or headers somewhere else, pass them as `status=` and `headers=`.
+
+## Check HTML
+
+```python
+from captcha_detector import detect_html
+
+r = detect_html(html, url="https://shop.example/", status=403, headers={"server": "cloudflare"})
+```
+
+## In a real browser
+
+Raw HTML only shows what the server sent, and can't tell what is on screen. In a browser the detector sees what scripts added and whether the captcha is visible.
+
+```python
+from playwright.sync_api import sync_playwright
+from captcha_detector import detect_in_page, wait_for_captcha
+
+with sync_playwright() as p:
+    page = p.chromium.launch().new_page()
+    response = page.goto("https://www.google.com/recaptcha/api2/demo")
+    r = detect_in_page(page, response=response)      # checks every frame, cross-origin ones too
+    print(r.summary)                                  # Captcha found: reCAPTCHA (v2-checkbox) [visible]
+
+    r = wait_for_captcha(page, timeout=10, visible=True)   # wait until one is on screen
+```
+
+Async: `await detect_in_page_async(page)` and `await wait_for_captcha_async(page)`.
+
+Selenium:
+
+```python
+from selenium import webdriver
+from captcha_detector import detect_selenium
+
+driver = webdriver.Chrome()
+driver.get("https://www.google.com/recaptcha/api2/demo")
+r = detect_selenium(driver)    # switches into each frame and back
+```
+
+Anything else that runs JavaScript can load `captcha_detector.BROWSER_SCRIPT` (it defines `window.CaptchaDetector`) or evaluate `captcha_detector.expression()`, then convert the result with `captcha_detector.from_js()`.
+
+## The result
+
+A `dict` (so `json.dumps` works) whose keys can also be read as attributes:
+
+```python
+{
+  "captcha": True,          # a captcha or bot check is on the page (shown, invisible or not rendered yet)
+  "visible": None,          # on screen right now: True/False in a browser, None for raw HTML
+  "challenge_page": False,  # the whole page is a bot check
+  "blocked": False,         # an access-denied page
+  "detections": [{
+      "id": "recaptcha", "name": "reCAPTCHA", "vendor": "Google",
+      "kind": "widget",     # widget | invisible | image | question | challenge-page | block-page | protection
+      "subtype": "v2-checkbox", "confidence": 0.99, "visible": None,
+      "evidence": [{"type": "scripts", "value": "https://www.google.com/recaptcha/api.js"},
+                   {"type": "elements", "value": ".g-recaptcha"}],
+      "site": "https://developers.google.com/recaptcha",
+  }],
+  "summary": "Captcha found: reCAPTCHA (v2-checkbox)",
+  "url": "https://shop.example/", "mode": "html", "version": "1.0.0",
+}
+```
+
+`kind: "protection"` means a bot-protection service is loaded (DataDome, Akamai, PerimeterX…) but no captcha is shown; it does not set `captcha`. When the reCAPTCHA or hCaptcha image challenge is open, `details["challenge_open"]` is `True`.
+
+Options for every function: `min_confidence` (0..1, default 0.5) and `signatures` (your own list; `SIGNATURES + mine` adds to the built-in ones).
+
+## Command line
+
+```bash
+captcha-detector https://www.google.com/recaptcha/api2/demo
+captcha-detector https://example.com --browser --json      # needs: pip install playwright
+curl -s https://example.com | captcha-detector -
+curl -s "https://scraper-api.example/v1?url=..." | captcha-detector -
+```
+
+Options: `--browser`, `--headful`, `--wait MS`, `--json`, `--fail` (exit code 1 when a captcha is found), `--min 0..1`. Also `python -m captcha_detector`.
+
+## Add your own signature
+
+```python
+from captcha_detector import SIGNATURES, detect_html
+
+acme = {
+    "id": "acme-check", "name": "ACME bot check", "kind": "challenge-page",
+    "title": [(r"^acme says hold on", 0.9)],                  # regex, or (regex, weight)
+    "scripts": [r"cdn\.acme-shield\.example/"],
+    "elements": ["#acme-check", {"sel": "form", "attr": ["action"], "re": r"/acme/verify", "w": 0.9}],
+    "refine": lambda d, x: d if x.short else None,             # optional: adjust or drop a match
+}
+r = detect_html(html, signatures=SIGNATURES + [acme])
+```
+
+Matchers: `scripts`, `frames`, `elements` (CSS: tag, `#id`, `.class`, `[attr op "v" i]`, `:not()`), `inline` (inline script text), `urls`, `title`, `text` (short pages only, unless `(re, w, "any")`), `cookies`, `headers` (`(name, re, w)`), `status`. Matches combine into a confidence; the default threshold is 0.5.
+
+To add a product for everyone, add it to `src/signatures.js` in the [repository](https://github.com/ScrapePass/captcha-detector): the JavaScript and Python packages share one signature database.
+
+## How it stays in step with the JavaScript package
+
+The signature database (`signatures.json`) is generated from the JavaScript source, and the test suite checks that the Python engine gives exactly the same result as the JavaScript engine on every test page.
+
+## License
+
+MIT

captcha_detector-1.0.0/README.md

@@ -0,0 +1,157 @@
+# captcha-detector for Python
+
+**Does this web page have a captcha?** The Python version of [captcha-detector](https://github.com/ScrapePass/captcha-detector): the same 69 named captcha and bot-check products plus catch-all rules, the same answers, zero dependencies.
+
+- **Check what your scraper got back:** pass a `requests`, `httpx`, `aiohttp`, `curl_cffi`, Scrapy or urllib response, or the JSON a scraper API sent, and find out whether you got the real page or a captcha, a bot check or a block page.
+- **Every kind:** checkbox widgets, invisible/score captchas, puzzles and sliders, proof-of-work, image captchas, math and text questions, full-page bot checks ("Just a moment…", "Press & Hold"), and access-denied pages.
+- **Real browsers too:** Playwright (sync and async) and Selenium, cross-origin frames included, with `visible` telling you whether the captcha is on screen.
+
+```bash
+pip install captcha-detector
+```
+
+## Check a response
+
+```python
+import requests
+from captcha_detector import detect_response
+
+url = "https://shop.example/product/42"
+res = requests.get(url)
+r = detect_response(res)
+
+if r.captcha or r.challenge_page or r.blocked:
+    print("Not the real page:", r.summary)   # e.g. "Captcha found: DataDome captcha (slider) [visible]"
+else:
+    parse(res.text)
+```
+
+`detect_response()` takes:
+
+| Input | Example |
+|---|---|
+| `requests` / `httpx` / `curl_cffi` / `niquests` response | `detect_response(requests.get(url))` |
+| Scrapy response | `detect_response(response)` inside `parse()` |
+| `urllib.request` / `urllib3` response | `detect_response(urlopen(url))` |
+| `aiohttp` response | `await detect_response_async(resp)` |
+| HTML as `str` or `bytes` | `detect_response(html, url=url)` |
+| A scraper API's JSON (`str`, `dict` or `list`) | `detect_response(api_res.json(), url=target)` |
+
+### Results from scraper APIs
+
+HTML wrapped in JSON (`{"html": …}`, `{"result": {"content": …}}` and the like) is found on its own, along with the status code, headers and URL next to it.
+
+```python
+target = "https://shop.example/product/42"
+res = requests.get("https://scraper-api.example/v1", params={"url": target, "key": KEY})
+r = detect_response(res, url=target)
+if r.captcha or r.challenge_page or r.blocked:
+    ...  # retry with another proxy or provider, don't parse or store this one
+```
+
+Pass `url`, the page you asked the API to scrape, not the API's own address. Most scraper APIs answer `200` whatever the site did; that's fine, the page itself gives a captcha away. If your API reports the site's real status or headers somewhere else, pass them as `status=` and `headers=`.
+
+## Check HTML
+
+```python
+from captcha_detector import detect_html
+
+r = detect_html(html, url="https://shop.example/", status=403, headers={"server": "cloudflare"})
+```
+
+## In a real browser
+
+Raw HTML only shows what the server sent, and can't tell what is on screen. In a browser the detector sees what scripts added and whether the captcha is visible.
+
+```python
+from playwright.sync_api import sync_playwright
+from captcha_detector import detect_in_page, wait_for_captcha
+
+with sync_playwright() as p:
+    page = p.chromium.launch().new_page()
+    response = page.goto("https://www.google.com/recaptcha/api2/demo")
+    r = detect_in_page(page, response=response)      # checks every frame, cross-origin ones too
+    print(r.summary)                                  # Captcha found: reCAPTCHA (v2-checkbox) [visible]
+
+    r = wait_for_captcha(page, timeout=10, visible=True)   # wait until one is on screen
+```
+
+Async: `await detect_in_page_async(page)` and `await wait_for_captcha_async(page)`.
+
+Selenium:
+
+```python
+from selenium import webdriver
+from captcha_detector import detect_selenium
+
+driver = webdriver.Chrome()
+driver.get("https://www.google.com/recaptcha/api2/demo")
+r = detect_selenium(driver)    # switches into each frame and back
+```
+
+Anything else that runs JavaScript can load `captcha_detector.BROWSER_SCRIPT` (it defines `window.CaptchaDetector`) or evaluate `captcha_detector.expression()`, then convert the result with `captcha_detector.from_js()`.
+
+## The result
+
+A `dict` (so `json.dumps` works) whose keys can also be read as attributes:
+
+```python
+{
+  "captcha": True,          # a captcha or bot check is on the page (shown, invisible or not rendered yet)
+  "visible": None,          # on screen right now: True/False in a browser, None for raw HTML
+  "challenge_page": False,  # the whole page is a bot check
+  "blocked": False,         # an access-denied page
+  "detections": [{
+      "id": "recaptcha", "name": "reCAPTCHA", "vendor": "Google",
+      "kind": "widget",     # widget | invisible | image | question | challenge-page | block-page | protection
+      "subtype": "v2-checkbox", "confidence": 0.99, "visible": None,
+      "evidence": [{"type": "scripts", "value": "https://www.google.com/recaptcha/api.js"},
+                   {"type": "elements", "value": ".g-recaptcha"}],
+      "site": "https://developers.google.com/recaptcha",
+  }],
+  "summary": "Captcha found: reCAPTCHA (v2-checkbox)",
+  "url": "https://shop.example/", "mode": "html", "version": "1.0.0",
+}
+```
+
+`kind: "protection"` means a bot-protection service is loaded (DataDome, Akamai, PerimeterX…) but no captcha is shown; it does not set `captcha`. When the reCAPTCHA or hCaptcha image challenge is open, `details["challenge_open"]` is `True`.
+
+Options for every function: `min_confidence` (0..1, default 0.5) and `signatures` (your own list; `SIGNATURES + mine` adds to the built-in ones).
+
+## Command line
+
+```bash
+captcha-detector https://www.google.com/recaptcha/api2/demo
+captcha-detector https://example.com --browser --json      # needs: pip install playwright
+curl -s https://example.com | captcha-detector -
+curl -s "https://scraper-api.example/v1?url=..." | captcha-detector -
+```
+
+Options: `--browser`, `--headful`, `--wait MS`, `--json`, `--fail` (exit code 1 when a captcha is found), `--min 0..1`. Also `python -m captcha_detector`.
+
+## Add your own signature
+
+```python
+from captcha_detector import SIGNATURES, detect_html
+
+acme = {
+    "id": "acme-check", "name": "ACME bot check", "kind": "challenge-page",
+    "title": [(r"^acme says hold on", 0.9)],                  # regex, or (regex, weight)
+    "scripts": [r"cdn\.acme-shield\.example/"],
+    "elements": ["#acme-check", {"sel": "form", "attr": ["action"], "re": r"/acme/verify", "w": 0.9}],
+    "refine": lambda d, x: d if x.short else None,             # optional: adjust or drop a match
+}
+r = detect_html(html, signatures=SIGNATURES + [acme])
+```
+
+Matchers: `scripts`, `frames`, `elements` (CSS: tag, `#id`, `.class`, `[attr op "v" i]`, `:not()`), `inline` (inline script text), `urls`, `title`, `text` (short pages only, unless `(re, w, "any")`), `cookies`, `headers` (`(name, re, w)`), `status`. Matches combine into a confidence; the default threshold is 0.5.
+
+To add a product for everyone, add it to `src/signatures.js` in the [repository](https://github.com/ScrapePass/captcha-detector): the JavaScript and Python packages share one signature database.
+
+## How it stays in step with the JavaScript package
+
+The signature database (`signatures.json`) is generated from the JavaScript source, and the test suite checks that the Python engine gives exactly the same result as the JavaScript engine on every test page.
+
+## License
+
+MIT

captcha_detector-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "captcha-detector"
+version = "1.0.0"
+description = "Does this web page have a captcha? Detects 69 captcha and bot-check products (reCAPTCHA, hCaptcha, Turnstile, DataDome, PerimeterX...) in HTML, scraper API results, Playwright and Selenium. Zero dependencies."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "ScrapePass" }]
+requires-python = ">=3.8"
+keywords = ["captcha", "captcha-detection", "recaptcha", "hcaptcha", "turnstile", "cloudflare", "bot-detection", "web-scraping", "playwright", "selenium", "datadome"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.30"]
+selenium = ["selenium>=4"]
+
+[project.urls]
+Homepage = "https://github.com/ScrapePass/captcha-detector"
+Source = "https://github.com/ScrapePass/captcha-detector/tree/main/python"
+Issues = "https://github.com/ScrapePass/captcha-detector/issues"
+
+[project.scripts]
+captcha-detector = "captcha_detector.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+captcha_detector = ["signatures.json", "captcha-detector.js"]

captcha_detector-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

captcha_detector-1.0.0/src/captcha_detector/__init__.py

@@ -0,0 +1,55 @@
+"""captcha-detector: does this web page have a captcha?
+
+    from captcha_detector import detect_html, detect_response
+
+    r = detect_response(requests.get(url), url=url)
+    if r.captcha or r.challenge_page or r.blocked:
+        print(r.summary)
+
+Browser helpers (Playwright, Selenium) are in captcha_detector.browser and re-exported here.
+"""
+
+from .engine import (
+    SIGNATURES,
+    VERSION,
+    Detection,
+    Result,
+    analyze,
+    detect_html,
+    from_js,
+    merge_results,
+    snapshot_from_html,
+)
+from .response import detect_response, detect_response_async
+from .browser import (
+    BROWSER_SCRIPT,
+    detect_in_page,
+    detect_in_page_async,
+    detect_selenium,
+    expression,
+    wait_for_captcha,
+    wait_for_captcha_async,
+)
+
+__version__ = VERSION
+
+__all__ = [
+    "VERSION",
+    "SIGNATURES",
+    "Detection",
+    "Result",
+    "detect_html",
+    "detect_response",
+    "detect_response_async",
+    "detect_in_page",
+    "detect_in_page_async",
+    "wait_for_captcha",
+    "wait_for_captcha_async",
+    "detect_selenium",
+    "merge_results",
+    "analyze",
+    "snapshot_from_html",
+    "from_js",
+    "expression",
+    "BROWSER_SCRIPT",
+]

captcha_detector-1.0.0/src/captcha_detector/__main__.py

@@ -0,0 +1,112 @@
+"""Command line: python -m captcha_detector <url | file.html | -> [options]  (also installed as `captcha-detector`)."""
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+
+from . import VERSION, detect_html, detect_response
+
+UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
+
+EPILOG = """examples:
+  captcha-detector https://www.google.com/recaptcha/api2/demo
+  captcha-detector https://example.com --browser --json
+  curl -s https://example.com | captcha-detector -
+  curl -s "https://scraper-api.example/v1?url=..." | captcha-detector -   # HTML or a scraper API's JSON
+"""
+
+
+def from_url(url, a):
+    req = urllib.request.Request(url, headers={"User-Agent": UA, "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "Accept-Language": "en-US,en;q=0.9"})
+    try:
+        res = urllib.request.urlopen(req, timeout=30)
+    except urllib.error.HTTPError as e:  # 403/429/503 pages are what we want to see
+        res = e
+    body = res.read()
+    charset = res.headers.get_content_charset() or "utf-8"
+    return detect_html(body.decode(charset, "replace"), url=res.geturl(), status=res.getcode(), headers=list(res.headers.items()), min_confidence=a.min)
+
+
+def from_browser(url, a):
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        raise SystemExit("captcha-detector: --browser needs Playwright: pip install playwright && playwright install chromium")
+    from .browser import detect_in_page
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=not a.headful)
+        try:
+            page = browser.new_context(viewport={"width": 1280, "height": 900}).new_page()
+            response = page.goto(url, wait_until="domcontentloaded", timeout=45000)
+            try:
+                page.wait_for_load_state("load", timeout=15000)
+            except Exception:
+                pass
+            if a.wait > 0:
+                page.wait_for_timeout(a.wait)
+            return detect_in_page(page, response=response, min_confidence=a.min)
+        finally:
+            browser.close()
+
+
+def show(r):
+    tty = sys.stdout.isatty()
+
+    def c(code, s):
+        return "\x1b[%sm%s\x1b[0m" % (code, s) if tty else s
+
+    head = c("33;1", "⚠ Captcha found") if r["captcha"] else c("31;1", "⛔ Blocked") if r["blocked"] else c("32;1", "✓ No captcha found")
+    print(head + ("  " + c("2", r["url"]) if r["url"] else ""))
+    if r["captcha"]:
+        vis = "unknown (static HTML)" if r["visible"] is None else str(r["visible"]).lower()
+        print(c("2", "  visible: %s   challenge page: %s" % (vis, str(r["challenge_page"]).lower())))
+    for d in r["detections"]:
+        bits = [d["vendor"], d["kind"] + ("/" + d["subtype"] if d["subtype"] else ""), "visible" if d["visible"] is True else "not visible" if d["visible"] is False else None, "%d%%" % int(d["confidence"] * 100 + 0.5)]
+        print("  • %s %s" % (c("1", d["name"]), c("2", "— " + " · ".join(b for b in bits if b))))
+        for e in d["evidence"][:4]:
+            print(c("2", "      %s: %s%s" % (e["type"], e["value"], " (in frame)" if e.get("frame") else "")))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="captcha-detector", description="captcha-detector %s: does this page have a captcha?" % VERSION, epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input", help="a URL, an HTML (or scraper API JSON) file, or - for stdin")
+    ap.add_argument("--browser", action="store_true", help="open the page in a real browser (needs: pip install playwright) and check the live page and its frames")
+    ap.add_argument("--headful", action="store_true", help="show the browser window (with --browser)")
+    ap.add_argument("--wait", type=int, default=3000, metavar="MS", help="wait after the page loads, with --browser (default 3000)")
+    ap.add_argument("--json", action="store_true", help="print the full result as JSON")
+    ap.add_argument("--fail", action="store_true", help="exit with code 1 when a captcha is found")
+    ap.add_argument("--min", type=float, default=0.5, metavar="0..1", help="minimum confidence (default 0.5)")
+    ap.add_argument("--version", action="version", version=VERSION)
+    a = ap.parse_args(argv)
+    try:
+        if a.input == "-":
+            r = detect_response(sys.stdin.buffer.read(), min_confidence=a.min)
+        elif re.match(r"^https?://", a.input, re.I):
+            r = from_browser(a.input, a) if a.browser else from_url(a.input, a)
+        elif os.path.exists(a.input):
+            with open(a.input, "rb") as f:
+                r = detect_response(f.read(), min_confidence=a.min)
+        elif re.match(r"^[\w-]+(\.[\w-]+)+", a.input):
+            url = "https://" + a.input
+            r = from_browser(url, a) if a.browser else from_url(url, a)
+        else:
+            raise ValueError("Not a URL or a file: " + a.input)
+    except SystemExit:
+        raise
+    except Exception as e:
+        print("captcha-detector: %s" % e, file=sys.stderr)
+        return 2
+    if a.json:
+        print(json.dumps(r, indent=2, ensure_ascii=False))
+    else:
+        show(r)
+    return 1 if a.fail and r["captcha"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())