proxy-scraper-cli 1.12.0__tar.gz → 1.14.0__tar.gz

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxy-scraper-cli
-Version: 1.12.0
+Version: 1.14.0
 Summary: Finds free HTTP, SOCKS4 and SOCKS5 proxies that actually work: 700+ sources, real checks, honeypot filtering and a rotating local proxy server.
 Author: Maximilian Feix
 License-Expression: MIT
@@ -699,6 +699,13 @@ pip download requests   # git, pip, npm & co. now go through the pool
 
 `proxy` is the fastest one, `file` a text file with all of them (up to `limit`, default 20), `count` how many. Without a match the step fails, unless `fail-if-empty: false`.
 
+**In the shell, without a scan** – `--pick` takes proxies from the hourly list in about half a second
+
+```bash
+curl -x "$(proxy-scraper --pick --https-only --min-uptime 90)" https://api.ipify.org
+proxy-scraper --pick 10 --country DE --works-on google > de.txt
+```
+
 **Without installing anything** – straight from the live list
 
 ```bash
@@ -743,6 +750,7 @@ curl.exe -x (Get-Content "$run\all.txt" -TotalCount 1) http://api.ipify.org
 | `--discover` | search GitHub for new sources right now |
 | `--no-cache` | download every list again (unchanged ones are normally skipped via ETag) |
 | `--list-sources [N]` | show the source ranking (add `--json` for scripts: url, status, hit rate, checks, last change) |
+| `--pick [N]` | print N proxies (default 1) from the hourly checked list and exit – no scan, same filters, plus `--min-uptime PERCENT` and `--works-on google,reddit,…` |
 | `--serve-host ADDR` | where the proxy server listens (default `127.0.0.1`; `0.0.0.0` for Docker, with a warning) |
 | `--serve-password SECRET` | clients must send this password in the proxy login; better set `PROXY_SCRAPER_SERVE_PASSWORD` |
 | `--rotate STRATEGY` · `--sticky SEC` | how the proxy server picks proxies, see [above](#proxy-server) |

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/README.md

@@ -658,6 +658,13 @@ pip download requests   # git, pip, npm & co. now go through the pool
 
 `proxy` is the fastest one, `file` a text file with all of them (up to `limit`, default 20), `count` how many. Without a match the step fails, unless `fail-if-empty: false`.
 
+**In the shell, without a scan** – `--pick` takes proxies from the hourly list in about half a second
+
+```bash
+curl -x "$(proxy-scraper --pick --https-only --min-uptime 90)" https://api.ipify.org
+proxy-scraper --pick 10 --country DE --works-on google > de.txt
+```
+
 **Without installing anything** – straight from the live list
 
 ```bash
@@ -702,6 +709,7 @@ curl.exe -x (Get-Content "$run\all.txt" -TotalCount 1) http://api.ipify.org
 | `--discover` | search GitHub for new sources right now |
 | `--no-cache` | download every list again (unchanged ones are normally skipped via ETag) |
 | `--list-sources [N]` | show the source ranking (add `--json` for scripts: url, status, hit rate, checks, last change) |
+| `--pick [N]` | print N proxies (default 1) from the hourly checked list and exit – no scan, same filters, plus `--min-uptime PERCENT` and `--works-on google,reddit,…` |
 | `--serve-host ADDR` | where the proxy server listens (default `127.0.0.1`; `0.0.0.0` for Docker, with a warning) |
 | `--serve-password SECRET` | clients must send this password in the proxy login; better set `PROXY_SCRAPER_SERVE_PASSWORD` |
 | `--rotate STRATEGY` · `--sticky SEC` | how the proxy server picks proxies, see [above](#proxy-server) |

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/proxy_scraper_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxy-scraper-cli
-Version: 1.12.0
+Version: 1.14.0
 Summary: Finds free HTTP, SOCKS4 and SOCKS5 proxies that actually work: 700+ sources, real checks, honeypot filtering and a rotating local proxy server.
 Author: Maximilian Feix
 License-Expression: MIT
@@ -699,6 +699,13 @@ pip download requests   # git, pip, npm & co. now go through the pool
 
 `proxy` is the fastest one, `file` a text file with all of them (up to `limit`, default 20), `count` how many. Without a match the step fails, unless `fail-if-empty: false`.
 
+**In the shell, without a scan** – `--pick` takes proxies from the hourly list in about half a second
+
+```bash
+curl -x "$(proxy-scraper --pick --https-only --min-uptime 90)" https://api.ipify.org
+proxy-scraper --pick 10 --country DE --works-on google > de.txt
+```
+
 **Without installing anything** – straight from the live list
 
 ```bash
@@ -743,6 +750,7 @@ curl.exe -x (Get-Content "$run\all.txt" -TotalCount 1) http://api.ipify.org
 | `--discover` | search GitHub for new sources right now |
 | `--no-cache` | download every list again (unchanged ones are normally skipped via ETag) |
 | `--list-sources [N]` | show the source ranking (add `--json` for scripts: url, status, hit rate, checks, last change) |
+| `--pick [N]` | print N proxies (default 1) from the hourly checked list and exit – no scan, same filters, plus `--min-uptime PERCENT` and `--works-on google,reddit,…` |
 | `--serve-host ADDR` | where the proxy server listens (default `127.0.0.1`; `0.0.0.0` for Docker, with a warning) |
 | `--serve-password SECRET` | clients must send this password in the proxy login; better set `PROXY_SCRAPER_SERVE_PASSWORD` |
 | `--rotate STRATEGY` · `--sticky SEC` | how the proxy server picks proxies, see [above](#proxy-server) |

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/proxy_scraper_cli.egg-info/SOURCES.txt

@@ -92,6 +92,7 @@ tests/test_pages.py
 tests/test_parsing.py
 tests/test_parsing_fuzz.py
 tests/test_paths.py
+tests/test_pick.py
 tests/test_pipeline.py
 tests/test_proxy_pages.py
 tests/test_proxy_sources.py

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/proxyscraper/__init__.py

@@ -1,7 +1,7 @@
 """proxy-scraper: collects public HTTP/SOCKS4/SOCKS5 proxies from hundreds of sources, checks them
 in parallel with its own protocol handshakes and learns which sources deliver good proxies."""
 
-__version__ = "1.12.0"
+__version__ = "1.14.0"
 
 
 def __getattr__(name):

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/proxyscraper/cli.py

@@ -34,6 +34,7 @@ from .output import has_latest_results
 from .parsing import PROXY_TYPES
 from .preferences import load_last_argv, save_last_argv
 from .server.pool import STRATEGIES
+from .sites import SITES
 from .targets import parse_target
 from .ui import ACCENT, BAD, MUTED, banner, note, render_source_ranking, widgets
 from .ui.keys import is_interactive
@@ -62,6 +63,36 @@ def list_sources(limit: int, as_json: bool = False) -> int:
     return 0
 
 
+def pick(args) -> int:
+    """--pick: proxies from the hourly list, nothing but their URLs on stdout (for $(…) in a shell)."""
+    from .api import live_proxies
+
+    try:
+        found = live_proxies(types=args.types, countries=args.country or "", https=args.https_only,
+                             anonymity=args.anonymity or "", max_latency=args.max_latency,
+                             no_datacenter=args.no_datacenter, no_blocklisted=args.no_blocklisted,
+                             min_uptime=args.min_uptime, works_on=args.works_on, limit=args.pick)
+    except (ConnectionError, ValueError) as e:
+        print(f"proxy-scraper: {e}", file=sys.stderr)
+        return 1
+    if not found:
+        print("proxy-scraper: no proxy in the live list matches these filters right now – loosen them, "
+              "or run a scan of your own", file=sys.stderr)
+        return 1
+    sys.stdout.write("".join(f"{p.url}\n" for p in found))
+    return 0
+
+
+def site_list(text: str) -> List[str]:
+    """argparse type for --works-on: google,reddit -> ["google", "reddit"]"""
+    names = [n.strip().lower() for n in text.split(",") if n.strip()]
+    known = [s.name for s in SITES]
+    for n in names:
+        if n not in known:
+            raise argparse.ArgumentTypeError(f"unknown site {n!r}, use {', '.join(known)}")
+    return names
+
+
 def _number(kind, minimum, strict=False, maximum=None):
     """argparse type for numbers with limits – with an understandable error message."""
     def parse(text: str):
@@ -96,6 +127,7 @@ def export_list(text: str) -> List[str]:
 positive_int = _number(int, 1)
 port_number = _number(int, 1, maximum=65535)
 non_negative_int = _number(int, 0)
+percent = _number(int, 0, maximum=100)
 positive_float = _number(float, 0, strict=True)
 non_negative_float = _number(float, 0)
 
@@ -166,6 +198,16 @@ def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
     f.add_argument("--target", action="append", type=target_url, metavar="URL",
                    help="only proxies that reach this site (repeatable), e.g. --target google.com")
 
+    live = p.add_argument_group("Live list (no scan)")
+    live.add_argument("--pick", nargs="?", const=1, type=positive_int, metavar="N",
+                      help="print N proxies (default 1) from the hourly checked list that match the filters above, "
+                           "one URL per line, and exit – e.g. curl -x \"$(proxy-scraper --pick --https-only)\" …")
+    live.add_argument("--min-uptime", type=percent, default=0, metavar="PERCENT",
+                      help="with --pick: only proxies on the list in at least this share of the week's checks")
+    live.add_argument("--works-on", type=site_list, default=[], metavar="SITES",
+                      help=f"with --pick: only proxies that got through to these sites in the last check "
+                           f"({', '.join(s.name for s in SITES)})")
+
     v = p.add_argument_group("Proxy server")
     v.add_argument("--serve", nargs="?", const=DEFAULT_SERVE_PORT, default=0, type=port_number, metavar="PORT",
                    help=f"serve the hits as a rotating proxy on 127.0.0.1:PORT after the run "
@@ -209,6 +251,14 @@ def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
     args = p.parse_args(argv)
     if args.json and args.list_sources is None:
         p.error("--json only works together with --list-sources")
+    if (args.min_uptime or args.works_on) and args.pick is None:
+        p.error("--min-uptime and --works-on only work together with --pick")
+    if args.pick is not None:  # --pick exits right away: options for a scan or the server would be silently ignored
+        scan_only = [flag for dest, flag in (("target", "--target"), ("serve", "--serve"), ("recheck", "--recheck"),
+                                             ("want", "--want"), ("output", "-o/--output"), ("export", "--export"))
+                     if getattr(args, dest) != p.get_default(dest)]
+        if scan_only:
+            p.error(f"--pick takes proxies from the live list and exits – {', '.join(scan_only)} belong to a scan")
     return args
 
 
@@ -260,6 +310,8 @@ def run(argv: Optional[List[str]] = None) -> int:
         return mcp_main()
     if args.list_sources is not None:
         return list_sources(args.list_sources, args.json)
+    if args.pick is not None:
+        return pick(args)
     opts = RunOptions.from_args(args)
     if opts.output == STDOUT:
         widgets.console = Console(highlight=False, stderr=True)  # stdout only carries the hits

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/proxyscraper/publish.py

@@ -70,7 +70,9 @@ def stats_for(rows: List[dict], now: datetime) -> dict:
         if any(r.get("blocklisted") is not None for r in rows) else None,
         "stable": sum(1 for r in rows if r.get("streak", 0) >= STABLE_RUNS),
         # proxies that got through to Google, Reddit, ... in the site check after the run (sites.py)
-        "sites": {s.name: sum(1 for r in rows if (r.get("sites") or {}).get(s.name)) for s in SITES},
+        # None when a site wasn't checked at all (the step failed, its DNS lookup didn't work) – not a measured 0
+        "sites": {s.name: sum(1 for r in rows if (r.get("sites") or {}).get(s.name))
+                  if any(s.name in (r.get("sites") or {}) for r in rows) else None for s in SITES},
         "run_hours": RUN_HOURS,
         "countries": dict(Counter(r["country"] for r in rows if r.get("country")).most_common(15)),
         "median_latency": round(statistics.median(r["latency"] for r in rows)) if rows else 0,

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/proxyscraper/site/index.html

@@ -22,6 +22,9 @@
 <meta property="og:description" content="Every proxy on this list passed a real handshake, a honeypot check and a content check. Re-checked every hour.">
 <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='18' fill='%23D4F77A'/%3E%3Cpath d='M13 31.5 26.5 44.5 51 18' fill='none' stroke='%23121113' stroke-width='5.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3Ccircle cx='13' cy='31.5' r='4.6' fill='%23121113'/%3E%3Ccircle cx='51' cy='18' r='4.6' fill='%23121113'/%3E%3Ccircle cx='26.5' cy='44.5' r='7.6' fill='%23D4F77A' stroke='%23121113' stroke-width='5'/%3E%3C/svg%3E">
 <script type="application/ld+json">
+{"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Are free proxies safe to use?", "acceptedAnswer": {"@type": "Answer", "text": "They're run by strangers, so treat them as untrusted. Anything that isn't encrypted can be read by whoever runs the proxy – never send passwords or personal data through one. Every proxy on this list has passed a content check (it didn't change a known page), and the HTTPS ones tunnel TLS that's verified end to end, so an https:// site can't be read or altered. That makes them fine for scraping public pages or seeing a site from another country, not for your bank."}}, {"@type": "Question", "name": "Why do most free proxies not work?", "acceptedAnswer": {"@type": "Answer", "text": "They don't live long. Of the proxies that drop off this list again, most are gone by the next hourly check, and only a few last a whole day – the weekly report tracks it. Many lists never re-check, so a large share of what they hold is long dead, and some of what still answers are honeypots or proxies that inject ads."}}, {"@type": "Question", "name": "How often is the list updated?", "acceptedAnswer": {"@type": "Answer", "text": "Every hour. GitHub Actions collects proxies from 700+ public lists, checks them and publishes whatever passed. This page loads the new list by itself when a run lands."}}, {"@type": "Question", "name": "Can I use it in my own projects?", "acceptedAnswer": {"@type": "Answer", "text": "Yes. The code is open source under the MIT license, and the lists are free to use, including in commercial projects. The proxies themselves belong to other people, so stick to the terms of the sites you visit through them."}}, {"@type": "Question", "name": "How do I use it from Python or an AI agent?", "acceptedAnswer": {"@type": "Answer", "text": "From Python: pip install proxy-scraper-cli, then live_proxies() returns the checked list with filters for country, protocol, uptime and the sites a proxy gets through to. AI agents like Claude Code or Cursor can use the MCP server, which gives them working proxies and can load pages through them."}}, {"@type": "Question", "name": "A proxy from the list doesn't work for me – why?", "acceptedAnswer": {"@type": "Answer", "text": "It worked from GitHub's servers in the last run, but free proxies come and go, and some block certain networks. proxy-scraper --recheck live checks the list again from your own connection in about 30 seconds and keeps what works from there."}}]}
+</script>
+<script type="application/ld+json">
 {"@context": "https://schema.org", "@type": "Dataset",
  "name": "Free proxy list, checked every hour",
  "description": "HTTP, SOCKS4 and SOCKS5 proxies from 700+ public lists that passed a real handshake, a honeypot check on two sites and a content check. With country, provider, latency, anonymity and HTTPS support.",
@@ -343,6 +346,25 @@
   .status .next:not(:empty)::before { content: " · "; }
   .bookmarklet .btn { cursor: grab; margin: 6px 0 4px; }
   .link-btn { font: inherit; color: var(--text); background: none; border: 0; padding: 0; text-decoration: underline; cursor: pointer; }
+  /* Why this list: one question per row, what a typical list says against what was measured here */
+  .ledger { border-top: 1px solid var(--line); }
+  .ledger-row { display: grid; grid-template-columns: minmax(0, 1.1fr) minmax(0, .9fr) minmax(0, 1.6fr); gap: 8px 32px; padding: 20px 0;
+                border-bottom: 1px solid var(--line); align-items: baseline; }
+  .ledger-head { padding: 14px 0; color: var(--muted); font-size: 14px; }
+  .ledger-row .q { font-size: 18px; font-weight: 500; letter-spacing: -.01em; }
+  .ledger-row .them { color: var(--muted); }
+  .ledger-row .us b { color: var(--signal-ink); font-weight: 600; font-variant-numeric: tabular-nums; }
+  /* FAQ: opens on click, nothing moves on its own */
+  .faq-list { border-top: 1px solid var(--line); }
+  .faq-item { border-bottom: 1px solid var(--line); }
+  .faq-item summary { list-style: none; cursor: pointer; display: flex; justify-content: space-between; align-items: center; gap: 24px; padding: 22px 0; }
+  .faq-item summary::-webkit-details-marker { display: none; }
+  .faq-item summary h3 { margin: 0; font-size: clamp(18px, 2vw, 21px); font-weight: 500; letter-spacing: -.01em; }
+  .faq-item summary::after { content: ""; flex: none; width: 12px; height: 12px; border-right: 1.5px solid var(--muted); border-bottom: 1.5px solid var(--muted);
+                             transform: translateY(-3px) rotate(45deg); transition: transform .3s var(--ease); }
+  .faq-item[open] summary::after { transform: translateY(3px) rotate(225deg); }
+  .faq-item summary:focus-visible { outline: 2px solid var(--signal-ink); outline-offset: 4px; border-radius: 6px; }
+  .faq-item p { margin: 0 0 24px; max-width: 70ch; color: var(--muted); font-size: 17px; }
   .panel { background: var(--panel); border: 1px solid var(--line); border-radius: 22px; padding: clamp(22px, 3vw, 34px); }
 
   /* For AI agents: a real Claude Code exchange, revealed line by line once it scrolls in */
@@ -440,6 +462,9 @@
     .ctas { justify-content: flex-start; }
     .figures { grid-template-columns: minmax(0, 1fr); }
     .head-row, .agent, .closing { grid-template-columns: minmax(0, 1fr); }
+    .ledger-row { grid-template-columns: minmax(0, 1fr); gap: 4px; }
+    .ledger-head { display: none; }
+    .ledger-row .them::before { content: "Typical list: "; }
     .tools li { grid-template-columns: minmax(0, 1fr); gap: 2px; }
     .transcript p { grid-template-columns: minmax(0, 1fr); gap: 4px; }
     .head-row .intro-text { justify-self: start; }
@@ -507,7 +532,7 @@
   <div class="wrap">
     <a class="brand" href="#top" aria-label="proxy-scraper, back to top"><svg class="mark" aria-hidden="true"><use href="#mark"/></svg>proxy-scraper</a>
     <nav class="nav-links" aria-label="Sections">
-      <a href="#list">The list</a><a href="#agents">AI agents</a><a href="#checks">How it's checked</a><a href="#runs">Last runs</a><a href="#use">Use it</a>
+      <a href="#list">The list</a><a href="#agents">AI agents</a><a href="#checks">How it's checked</a><a href="#why">Why this one</a><a href="#runs">Last runs</a><a href="#use">Use it</a>
     </nav>
     <div class="nav-actions">
       <button class="toggle" id="theme" type="button" aria-label="Switch to light theme">
@@ -670,6 +695,23 @@
       </div>
     </div>
   </section>
+  <section class="block wrap" id="why" aria-labelledby="why-title">
+    <div class="head-row">
+      <h2 class="h2" id="why-title">Why this list, not another one</h2>
+      <p class="intro-text">Most free proxy lists are a dump of addresses that answered at some point. This is what you'd want to know before you use one – and what this list measured in the last run.</p>
+    </div>
+    <div class="ledger" role="table" aria-label="What a typical free proxy list tells you, and what this one measures">
+      <div class="ledger-row ledger-head" role="row"><span role="columnheader">What you'd want to know</span><span role="columnheader">A typical free list</span><span role="columnheader">Here, in the last run</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Is it a proxy at all?</span><span class="them" role="cell">That the port answered once</span><span class="us" role="cell">A real HTTP/SOCKS handshake and a page fetched through it: <b data-live="total">–</b> passed in the last run</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Is it a honeypot?</span><span class="them" role="cell">Often not checked</span><span class="us" role="cell">The exit IP is checked on two different sites and has to match both times</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Does it change the pages you load?</span><span class="them" role="cell">Not checked</span><span class="us" role="cell">A known page has to arrive byte for byte. Proxies that inject scripts or ads are dropped</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Does HTTPS work through it?</span><span class="them" role="cell">Sometimes a flag in the list</span><span class="us" role="cell">A verified TLS handshake through the tunnel: <b data-live="https">–</b> of them</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Will it still be there tomorrow?</span><span class="them" role="cell">Unknown</span><span class="us" role="cell">Every proxy's week of hourly checks. <b data-live="stable">–</b> were on the list for 90&nbsp;%+ of the week</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Does Google let it through?</span><span class="them" role="cell">Unknown</span><span class="us" role="cell">Tried on Google, Reddit, Amazon, Instagram and TikTok: <b data-live="google">–</b> got through to Google</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">Is it fast enough for real pages?</span><span class="them" role="cell">A latency number, if any</span><span class="us" role="cell">100&nbsp;KB downloaded through every HTTPS-capable one: half of them manage <b data-live="speed">–</b> or more</span></div>
+        <div class="ledger-row" role="row"><span class="q" role="rowheader">How fresh is it?</span><span class="them" role="cell">Scraped once, rarely checked again</span><span class="us" role="cell">Checked again every hour, the last run <b data-live="ago">–</b></span></div>
+    </div>
+  </section>
 
   <section class="block wrap" id="runs" aria-labelledby="runs-title">
     <div class="head-row">
@@ -748,6 +790,20 @@ proxy-scraper --want 50 --https-only</pre><button class="icon-btn" type="button"
 }</pre><button class="icon-btn" type="button" data-copy-pre aria-label="Copy the example"><svg aria-hidden="true"><use href="#i-copy"/></svg></button></div>
     </div>
   </section>
+  <section class="block wrap faq" id="faq" aria-labelledby="faq-title">
+    <div class="head-row">
+      <h2 class="h2" id="faq-title">Questions people ask</h2>
+      <p class="intro-text">Short answers. The <a href="https://github.com/maximilianfeix/proxy-scraper#faq">README</a> has more.</p>
+    </div>
+    <div class="faq-list">
+      <details class="faq-item"><summary><h3>Are free proxies safe to use?</h3></summary><p>They're run by strangers, so treat them as untrusted. Anything that isn't encrypted can be read by whoever runs the proxy – never send passwords or personal data through one. Every proxy on this list has passed a content check (it didn't change a known page), and the HTTPS ones tunnel TLS that's verified end to end, so an https:// site can't be read or altered. That makes them fine for scraping public pages or seeing a site from another country, not for your bank.</p></details>
+      <details class="faq-item"><summary><h3>Why do most free proxies not work?</h3></summary><p>They don't live long. Of the proxies that drop off this list again, most are gone by the next hourly check, and only a few last a whole day – the weekly report tracks it. Many lists never re-check, so a large share of what they hold is long dead, and some of what still answers are honeypots or proxies that inject ads.</p></details>
+      <details class="faq-item"><summary><h3>How often is the list updated?</h3></summary><p>Every hour. GitHub Actions collects proxies from 700+ public lists, checks them and publishes whatever passed. This page loads the new list by itself when a run lands.</p></details>
+      <details class="faq-item"><summary><h3>Can I use it in my own projects?</h3></summary><p>Yes. The code is open source under the MIT license, and the lists are free to use, including in commercial projects. The proxies themselves belong to other people, so stick to the terms of the sites you visit through them.</p></details>
+      <details class="faq-item"><summary><h3>How do I use it from Python or an AI agent?</h3></summary><p>From Python: pip install proxy-scraper-cli, then live_proxies() returns the checked list with filters for country, protocol, uptime and the sites a proxy gets through to. AI agents like Claude Code or Cursor can use the MCP server, which gives them working proxies and can load pages through them.</p></details>
+      <details class="faq-item"><summary><h3>A proxy from the list doesn't work for me – why?</h3></summary><p>It worked from GitHub's servers in the last run, but free proxies come and go, and some block certain networks. proxy-scraper --recheck live checks the list again from your own connection in about 30 seconds and keeps what works from there.</p></details>
+    </div>
+  </section>
   <section class="block wrap closing" aria-labelledby="star-title">
     <div>
       <h2 class="h2" id="star-title">Saved you an afternoon?</h2>
@@ -1311,6 +1367,10 @@ proxy-scraper --want 50 --https-only</pre><button class="icon-btn" type="button"
     sieve(rows, st.total);
     started = true;
     $("#final-n").textContent = fmt(st.total);
+    const live = { total: fmt(st.total), https: fmt(st.https), stable: fmt(rows.filter(r => (r.uptime_7d || 0) >= 90).length),
+                   google: st.sites && st.sites.google != null ? fmt(st.sites.google) : "–",
+                   speed: st.median_speed_kbps ? `${fmt(st.median_speed_kbps)} KB/s` : "–", ago: ago(st.updated) };
+    $$("[data-live]").forEach((el) => { el.textContent = live[el.dataset.live] ?? "–"; });
     const dc = st.datacenter != null ? ` ${pct(st.datacenter, st.total)} % exit from a datacenter` : "";
     const bl = st.blocklisted != null ? `${dc ? "," : ""} ${pct(st.blocklisted, st.total)} % from an IP on a spam blocklist` : "";
     $("#step5").textContent = `HTTPS with verified TLS, anonymity, country, provider and spam blocklists. This time ${fmt(st.https)} tunnel HTTPS and ${fmt(st.elite)} are elite.${dc}${bl}${dc || bl ? "." : ""}`;

proxy_scraper_cli-1.14.0/tests/test_pick.py

@@ -0,0 +1,44 @@
+"""proxy-scraper --pick: proxies from the hourly list on stdout, with the usual filters, no scan."""
+
+import pytest
+
+from proxyscraper import api, cli
+from tests.test_live_api import ROWS, STATS, fetch_from
+
+
+@pytest.fixture(autouse=True)
+def offline(monkeypatch):
+    rows = [dict(ROWS[0], sites={"google": True}), ROWS[1], ROWS[2]]
+    monkeypatch.setattr(api, "_live_fetch", fetch_from({"proxies.json": rows, "stats.json": STATS}))
+
+
+def test_one_proxy_by_default_and_nothing_else_on_stdout(capsys):
+    assert cli.run(["--pick"]) == 0
+    assert capsys.readouterr().out == "http://2.2.2.2:80\n"  # the fastest
+
+
+def test_the_usual_filters_apply(capsys):
+    assert cli.run(["--pick", "5", "--types", "socks4", "socks5", "--country", "DE", "--https-only"]) == 0
+    assert capsys.readouterr().out.splitlines() == ["socks4://3.3.3.3:4145", "socks5://1.1.1.1:1080"]
+    assert cli.run(["--pick", "--min-uptime", "90", "--works-on", "google"]) == 0
+    assert capsys.readouterr().out == "socks5://1.1.1.1:1080\n"
+
+
+def test_nothing_matching_is_exit_1_with_a_hint_on_stderr(capsys):
+    assert cli.run(["--pick", "--country", "JP"]) == 1
+    out = capsys.readouterr()
+    assert out.out == "" and "no proxy" in out.err.lower()
+
+
+def test_pick_only_filters_need_pick(capsys):
+    with pytest.raises(SystemExit):
+        cli.run(["--min-uptime", "90"])
+    assert "--pick" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("extra", [["--target", "discord.com"], ["--serve"], ["--recheck"], ["--want", "5"],
+                                   ["-o", "x.txt"], ["--export", "clash"]])
+def test_options_for_a_scan_are_an_error_not_ignored(extra, capsys):
+    with pytest.raises(SystemExit):
+        cli.run(["--pick", *extra])
+    assert "--pick" in capsys.readouterr().err

{proxy_scraper_cli-1.12.0 → proxy_scraper_cli-1.14.0}/tests/test_sites.py

@@ -119,7 +119,8 @@ def test_publish_writes_a_list_per_site_and_counts(tmp_path):
     assert (out / "works-with" / "reddit.txt").read_text() == ""
     assert (out / "works-with" / "amazon.txt").read_text() == ""
     stats = json.loads((out / "stats.json").read_text())
-    assert stats["sites"] == {"google": 1, "reddit": 0, "amazon": 0, "instagram": 0, "tiktok": 0}
+    # amazon, instagram and tiktok weren't checked at all in this run: that's "not measured", not zero
+    assert stats["sites"] == {"google": 1, "reddit": 0, "amazon": None, "instagram": None, "tiktok": None}
     assert (out / "works-with" / "tiktok.txt").read_text() == ""
     import csv
     with (out / "proxies.csv").open(newline="", encoding="utf-8") as fh: