proxy-scraper-cli 1.7.1__py3-none-any.whl

proxyscraper/cli.py

@@ -0,0 +1,269 @@
+"""Command line: read the arguments and start the matching flow."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from collections import Counter
+from typing import List, Optional
+
+from rich.console import Console
+from rich.text import Text
+
+from . import __version__
+from . import sources as srcs
+from .app import Run
+from .compat import ensure_utf8_output
+from .completion import CompletionAction
+from .exporters import EXPORTERS, parse_exports
+from .history import ProxyHistory
+from .options import (
+    DEFAULT_CONCURRENCY,
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_DISCOVER_REPOS,
+    DEFAULT_SERVE_PORT,
+    DEFAULT_TIMEOUT,
+    STDOUT,
+    RunOptions,
+)
+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 .targets import parse_target
+from .ui import ACCENT, BAD, MUTED, banner, note, render_source_ranking, widgets
+from .ui.keys import is_interactive
+from .ui.wizard import run_wizard
+
+
+def list_sources(limit: int) -> int:
+    """Ranking of every known source by learned hit rate."""
+    quality = srcs.SourceStats()
+    curated, _meta = srcs.load_source_file()
+    urls = set(curated) | set(srcs.load_discovered()) | set(quality.records)
+    ranking = quality.ranking(urls)
+    rows = [(u, r, quality.skip_reason(u) or "active") for u, r in ranking if r.runs][:limit]
+    reasons = Counter(quality.skip_reason(u) or "active" for u, _ in ranking)
+    widgets.console.print(banner())
+    render_source_ranking(rows, len(urls), reasons)
+    return 0
+
+
+def _number(kind, minimum, strict=False, maximum=None):
+    """argparse type for numbers with limits – with an understandable error message."""
+    def parse(text: str):
+        try:
+            value = kind(text)
+        except ValueError:
+            raise argparse.ArgumentTypeError(f"not a number: {text!r}") from None
+        if value < minimum or (strict and value == minimum):
+            raise argparse.ArgumentTypeError(f"must be {'greater than' if strict else 'at least'} {minimum}")
+        if maximum is not None and value > maximum:
+            raise argparse.ArgumentTypeError(f"must be at most {maximum}")
+        return value
+    return parse
+
+
+def target_url(text: str) -> str:
+    """argparse type for --target: normalized URL or an understandable error message."""
+    try:
+        return parse_target(text).url
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(str(e)) from None
+
+
+def export_list(text: str) -> List[str]:
+    """argparse type for --export: "proxychains,clash" or "all"."""
+    try:
+        return parse_exports(text)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(str(e)) from None
+
+
+positive_int = _number(int, 1)
+port_number = _number(int, 1, maximum=65535)
+non_negative_int = _number(int, 0)
+positive_float = _number(float, 0, strict=True)
+non_negative_float = _number(float, 0)
+
+
+def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="proxy-scraper",
+        description="Fast asynchronous proxy scraper & checker that learns which sources are worth it",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  proxy-scraper                                setup wizard (in a terminal)\n"
+            "  proxy-scraper -y                             collect and check everything right away\n"
+            "  proxy-scraper --want 50 --https-only         stop after 50 HTTPS-capable proxies\n"
+            "  proxy-scraper --country DE,AT,CH -l 20000    DACH only, the 20,000 best candidates\n"
+            "  proxy-scraper --types socks5 --anonymity elite --max-latency 1500\n"
+            "  proxy-scraper --target google.com --target discord.com --want 20\n"
+            "  proxy-scraper --recheck                      recheck the last hits + history\n"
+            "  proxy-scraper --recheck --serve              turn them into a rotating proxy right away\n"
+            "  proxy-scraper --list-sources                 source ranking\n"
+        ),
+    )
+    p.add_argument("-V", "--version", action="version", version=f"proxy-scraper {__version__}")
+    p.add_argument("--mcp", action="store_true",
+                   help="run as an MCP server over stdio, for AI agents like Claude Code (same as proxy-scraper-mcp; "
+                        'needs pip install "proxy-scraper-cli[mcp]")')
+    p.add_argument("--completion", action=CompletionAction, metavar="SHELL",
+                   help="print tab completion for bash, zsh or fish, e.g. eval \"$(proxy-scraper "
+                        "--completion zsh)\"")
+    m = p.add_argument_group("Start")
+    m.add_argument("-i", "--interactive", action="store_true",
+                   help="setup wizard: pick with the arrow keys what to look for "
+                        "(shows up automatically without arguments; other arguments are used as starting values)")
+    m.add_argument("-y", "--yes", action="store_true", help="skip the wizard and start right away with the defaults")
+
+    g = p.add_argument_group("Checks")
+    g.add_argument("-c", "--concurrency", type=positive_int, default=DEFAULT_CONCURRENCY,
+                   help=f"concurrent checks (default: {DEFAULT_CONCURRENCY})")
+    g.add_argument("-t", "--timeout", type=positive_float, default=DEFAULT_TIMEOUT,
+                   help=f"timeout per proxy in seconds (default: {DEFAULT_TIMEOUT:g})")
+    g.add_argument("--connect-timeout", type=positive_float, default=DEFAULT_CONNECT_TIMEOUT,
+                   help=f"max. time for the TCP connect in seconds (default: {DEFAULT_CONNECT_TIMEOUT:g})")
+    g.add_argument("--types", nargs="+", choices=list(PROXY_TYPES), default=list(PROXY_TYPES),
+                   help="which protocols (default: all)")
+    g.add_argument("-l", "--limit", type=non_negative_int, default=0,
+                   help="only check the N most promising proxies (by history & source quality)")
+    g.add_argument("--want", type=non_negative_int, default=0, metavar="N",
+                   help="stop as soon as N matching proxies are found")
+    g.add_argument("--fast", action="store_true",
+                   help="skip the HTTPS test (faster); confirmation and anonymity still run")
+    g.add_argument("--no-geo", action="store_true", help="don't look up countries")
+    g.add_argument("--no-dnsbl", action="store_true",
+                   help="don't look up whether exit IPs are on the SpamCop blocklist")
+    g.add_argument("--recheck", nargs="?", const="", metavar="FILE",
+                   help="only check proxies from FILE – without FILE: last run + history; "
+                        "'live': the live list from GitHub (seconds instead of minutes, e.g. with --serve)")
+
+    f = p.add_argument_group("Filters (for the result files)")
+    f.add_argument("--country", metavar="CC", help="only these countries, e.g. DE,AT,CH")
+    f.add_argument("--https-only", action="store_true", help="only proxies that can tunnel HTTPS sites")
+    f.add_argument("--anonymity", choices=["anonymous", "elite"], help="minimum anonymity")
+    f.add_argument("--max-latency", type=non_negative_int, default=0, metavar="MS",
+                   help="only proxies up to this latency")
+    f.add_argument("--no-datacenter", action="store_true",
+                   help="no proxies that exit from datacenters (cloud/hosting) – those often get blocked sooner")
+    f.add_argument("--no-blocklisted", action="store_true",
+                   help="no proxies whose exit IP is on the SpamCop blocklist – those often get captchas")
+    f.add_argument("--target", action="append", type=target_url, metavar="URL",
+                   help="only proxies that reach this site (repeatable), e.g. --target google.com")
+
+    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 "
+                        f"(default port: {DEFAULT_SERVE_PORT}); quick to start with --recheck")
+    v.add_argument("--rotate", choices=STRATEGIES, default="weighted",
+                   help="which proxy comes next: weighted (fast & reliable preferred, default), "
+                        "random, round-robin or fastest")
+    v.add_argument("--serve-host", default="127.0.0.1", metavar="ADDRESS",
+                   help="address of the proxy server (default: 127.0.0.1). 0.0.0.0 makes it reachable from outside – "
+                        "only for Docker with -p 127.0.0.1:8899:8899 or behind a firewall")
+    v.add_argument("--serve-password", default=os.environ.get("PROXY_SCRAPER_SERVE_PASSWORD", ""), metavar="SECRET",
+                   help="clients must send this password in the proxy login (HTTP and SOCKS5); better set "
+                        "PROXY_SCRAPER_SERVE_PASSWORD, so it doesn't show up in the process list")
+    v.add_argument("--serve-refill", type=non_negative_float, default=0, metavar="HOURS",
+                   help="every HOURS check fresh proxies in the background (the live list with --recheck live, "
+                        "otherwise the last run + history) and add the hits to the running server")
+    v.add_argument("--sticky", type=non_negative_int, default=0, metavar="SEC",
+                   help="the same target site keeps the same proxy for this long (e.g. for logins); "
+                        "per request this also works with the user name session-NAME")
+
+    o = p.add_argument_group("Output")
+    o.add_argument("-o", "--output", metavar="FILE",
+                   help="also write all hits as type://ip:port to this file; - prints them to stdout "
+                        "(the interface moves to stderr then)")
+    o.add_argument("--export", type=export_list, metavar="FORMATS",
+                   help=f"extra formats in the results folder: {', '.join(EXPORTERS)} or all "
+                        "(e.g. --export proxychains,clash)")
+
+    s = p.add_argument_group("Sources")
+    s.add_argument("--discover", action="store_true",
+                   help="look for new proxy lists on GitHub now (with a GitHub token this also runs once a day)")
+    s.add_argument("--no-discover", action="store_true", help="no automatic GitHub search")
+    s.add_argument("--discover-repos", type=non_negative_int, default=DEFAULT_DISCOVER_REPOS,
+                   help=f"max. repos during discovery (default: {DEFAULT_DISCOVER_REPOS}, 40 without a token)")
+    s.add_argument("--all-sources", action="store_true", help="also load dead, outdated and unreachable sources")
+    s.add_argument("--no-cache", action="store_true",
+                   help="reload every list completely (otherwise unchanged ones are skipped via ETag)")
+    s.add_argument("--list-sources", nargs="?", const=50, type=positive_int, metavar="N",
+                   help="show the source ranking by hit rate (default: top 50) and exit")
+    return p.parse_args(argv)
+
+
+def last_options() -> Optional[RunOptions]:
+    argv = load_last_argv()
+    if argv is None:
+        return None
+    try:
+        return RunOptions.from_args(parse_args(argv))
+    except SystemExit:  # the saved choice no longer fits the current options
+        return None
+
+
+def choose_interactively(initial: RunOptions) -> Optional[RunOptions]:
+    widgets.console.print(banner())
+    can_recheck = has_latest_results() or ProxyHistory.exists()
+    opts = run_wizard(initial, last_options(), can_recheck, widgets.console)
+    if opts is None:
+        return None
+    save_last_argv(opts.to_argv())
+    widgets.console.print(Text.assemble(
+        ("  ▸ ", ACCENT), ("Next time, directly: ", MUTED), (opts.to_command(), "bold"),
+    ))
+    return opts
+
+
+def wants_wizard(args: argparse.Namespace, argv: List[str]) -> bool:
+    """-i forces the wizard; without arguments it only shows up in a terminal. -y skips it."""
+    if args.interactive:
+        return True
+    return not argv and not args.yes and is_interactive()
+
+
+def install_uvloop() -> None:
+    try:
+        import uvloop  # optional (pip install "proxy-scraper-cli[fast]"), makes asyncio even faster
+    except ImportError:
+        return
+    uvloop.install()
+
+
+def run(argv: Optional[List[str]] = None) -> int:
+    ensure_utf8_output()
+    install_uvloop()
+    argv = sys.argv[1:] if argv is None else argv
+    args = parse_args(argv)
+    if args.mcp:  # before anything prints: stdout belongs to the MCP protocol from here on
+        from .mcp_entry import main as mcp_main
+        return mcp_main()
+    if args.list_sources is not None:
+        return list_sources(args.list_sources)
+    opts = RunOptions.from_args(args)
+    if opts.output == STDOUT:
+        widgets.console = Console(highlight=False, stderr=True)  # stdout only carries the hits
+    use_wizard = wants_wizard(args, argv)
+    if use_wizard:
+        if not is_interactive():
+            note("The setup wizard (-i) needs a terminal.", BAD, "✘")
+            return 2
+        opts = choose_interactively(opts)
+        if opts is None:
+            note("Cancelled – nothing was started.", MUTED, "ℹ")
+            return 0
+    try:
+        # after the wizard the banner is already on screen
+        return asyncio.run(Run(opts, show_banner=not use_wizard).execute())
+    except KeyboardInterrupt:
+        note("Interrupted.")
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(run())

proxyscraper/compat.py

@@ -0,0 +1,83 @@
+"""Platform differences in one place: file limits, Ctrl+C, console encoding.
+
+Windows has no `resource` module and no `loop.add_signal_handler`; asyncio programs run on the
+ProactorEventLoop (IOCP) there, which has no select() limit for sockets.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import signal
+import sys
+from contextlib import contextmanager
+from typing import Callable, Iterator
+
+IS_WINDOWS = sys.platform == "win32"
+
+try:
+    import resource
+except ImportError:  # Windows
+    resource = None
+
+
+def raise_fd_limit(wanted: int) -> int:
+    """Raise the allowed open files/sockets; returns the actual limit."""
+    if resource is None:
+        # no RLIMIT_NOFILE: the ProactorEventLoop doesn't limit sockets through such a limit
+        return wanted
+    soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
+    target = wanted if hard == resource.RLIM_INFINITY else min(wanted, hard)
+    if soft < target:
+        for t in (target, 10240, 4096):
+            try:
+                resource.setrlimit(resource.RLIMIT_NOFILE, (t, hard))
+                return t
+            except (ValueError, OSError):
+                continue
+    return resource.getrlimit(resource.RLIMIT_NOFILE)[0]
+
+
+@contextmanager
+def on_interrupt(loop: asyncio.AbstractEventLoop, callback: Callable[[], None]) -> Iterator[None]:
+    """Ctrl+C calls `callback` in the event loop instead of raising KeyboardInterrupt.
+
+    Unix: loop.add_signal_handler. Windows doesn't have that – there a classic
+    signal handler passes the callback into the loop thread-safely.
+    Afterwards the previous handler is active again in both cases.
+    """
+    previous = signal.getsignal(signal.SIGINT)
+    try:
+        loop.add_signal_handler(signal.SIGINT, callback)
+    except (NotImplementedError, RuntimeError):
+        try:
+            signal.signal(signal.SIGINT, lambda signum, frame: loop.call_soon_threadsafe(callback))
+        except ValueError:  # not in the main thread -> Ctrl+C keeps its default behavior
+            yield
+            return
+        try:
+            yield
+        finally:
+            if previous is not None:
+                signal.signal(signal.SIGINT, previous)
+        return
+    try:
+        yield
+    finally:
+        # remove_signal_handler() resets SIGINT to default_int_handler,
+        # not to a handler that was installed before
+        loop.remove_signal_handler(signal.SIGINT)
+        if previous is not None:
+            signal.signal(signal.SIGINT, previous)
+
+
+def ensure_utf8_output() -> None:
+    """Switch output to UTF-8 if the console uses something else (e.g. cp1252 on Windows).
+
+    Otherwise characters like ✔ or ▁ can raise a UnicodeEncodeError when redirecting to a file.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        encoding = (getattr(stream, "encoding", "") or "").lower().replace("-", "")
+        if encoding != "utf8" and hasattr(stream, "reconfigure"):
+            with contextlib.suppress(ValueError, OSError):  # e.g. an already closed or foreign stream
+                stream.reconfigure(encoding="utf-8", errors="replace")

proxyscraper/completion.py

@@ -0,0 +1,196 @@
+"""Tab completion for bash, zsh and fish – generated straight from the argparse parser.
+
+That way the script can never go stale: every new option shows up automatically, with its choices
+(--types, --rotate, …) and the start of its help text as the description (zsh, fish).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+SHELLS = ("bash", "zsh", "fish")
+PROG = "proxy-scraper"
+FILE_OPTIONS = {"--recheck": ("live",), "--output": ()}  # the value is a file path (or one of these words)
+OWN_HELP = {"help": "show help", "version": "show the version"}  # shorter than argparse's own texts
+
+
+@dataclass
+class Option:
+    flags: List[str]
+    help: str
+    takes_value: bool
+    optional_value: bool  # nargs="?": the value may be missing (--recheck, --serve)
+    choices: Tuple[str, ...]
+    is_file: bool
+    extra: Tuple[str, ...] = ()  # words that work instead of a file (--recheck live)
+    multi: bool = False  # nargs="+": several values in a row (--types http socks5)
+
+    @property
+    def long(self) -> Optional[str]:
+        return next((f for f in self.flags if f.startswith("--")), None)
+
+    @property
+    def short(self) -> Optional[str]:
+        return next((f for f in self.flags if not f.startswith("--")), None)
+
+
+def short_help(text: Optional[str], width: int = 60) -> str:
+    """Only the start of the help text: up to the first parenthesis, dash, semicolon or example."""
+    text = re.split(r" \(| – |; |,? e\.g\.", text or "")[0].strip()
+    return text if len(text) <= width else text[:width - 1].rstrip() + "…"
+
+
+def options(parser: argparse.ArgumentParser) -> List[Option]:
+    found = []
+    for action in parser._actions:  # argparse offers no public list
+        if not action.option_strings or action.help == argparse.SUPPRESS:
+            continue
+        takes_value = action.nargs != 0
+        found.append(Option(
+            flags=list(action.option_strings),
+            help=OWN_HELP.get(action.dest) or short_help(action.help),
+            takes_value=takes_value,
+            optional_value=action.nargs == "?",
+            choices=tuple(str(c) for c in action.choices or ()),
+            is_file=takes_value and any(f in FILE_OPTIONS for f in action.option_strings),
+            extra=next((FILE_OPTIONS[f] for f in action.option_strings if f in FILE_OPTIONS), ()),
+            multi=action.nargs in ("+", "*"),
+        ))
+    return found
+
+
+def bash(opts: List[Option]) -> str:
+    words = " ".join(f for o in opts for f in o.flags)
+    cases, multi = [], []
+    for o in opts:
+        if not o.takes_value or o.optional_value and not o.is_file:
+            continue
+        pattern = "|".join(o.flags)
+        if o.choices:
+            reply = f'COMPREPLY=($(compgen -W "{" ".join(o.choices)}" -- "$cur")); return ;;'
+            cases.append(f"        {pattern}) {reply}")
+            if o.multi:
+                multi.append(f"                {pattern}) {reply}")
+        elif o.is_file:
+            # line by line, so "file with spaces" stays one entry
+            extra = f'$(compgen -W "{" ".join(o.extra)}" -- "$cur") ' if o.extra else ""
+            cases.append(f"        {pattern}) compopt -o filenames 2>/dev/null; local IFS=$'\\n'; "
+                         f'COMPREPLY=({extra}$(compgen -f -- "$cur")); return ;;')
+        else:
+            cases.append(f"        {pattern}) return ;;  # freier Wert")
+    return f"""# bash completion for {PROG}
+# enable: eval "$({PROG} --completion bash)"  (e.g. in ~/.bashrc)
+_proxy_scraper() {{
+    local cur="${{COMP_WORDS[COMP_CWORD]}}" prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+    COMPREPLY=()
+    case "$prev" in
+{chr(10).join(cases)}
+    esac
+    # more values for options like --types http socks5: the last option before counts
+    if [[ "$cur" != -* ]]; then
+        local i
+        for ((i = COMP_CWORD - 1; i > 0; i--)); do
+            [[ "${{COMP_WORDS[i]}}" == -* ]] || continue
+            case "${{COMP_WORDS[i]}}" in
+{chr(10).join(multi)}
+            esac
+            break
+        done
+    fi
+    COMPREPLY=($(compgen -W "{words}" -- "$cur"))
+}}
+complete -F _proxy_scraper {PROG}
+"""
+
+
+def _zsh_escape(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("'", "'\\''").replace("[", "\\[").replace("]", "\\]")
+
+
+def zsh(opts: List[Option]) -> str:
+    specs = []
+    for o in opts:
+        repeat = "*" if o.long == "--target" else ""
+        # '(-c --concurrency)'{-c,--concurrency}'[…]' – the braces {} must not be inside quotes
+        spec = f"({' '.join(o.flags)}){repeat}'{{{','.join(o.flags)}}}'" if len(o.flags) > 1 else repeat + o.flags[0]
+        spec += f"[{_zsh_escape(o.help)}]"
+        if o.takes_value:
+            colon = "::" if o.optional_value else ":"
+            if o.choices:
+                action = f"({' '.join(o.choices)})"
+            elif o.is_file:
+                action = "{_files; compadd " + " ".join(o.extra) + "}" if o.extra else "_files"
+            else:
+                action = " "
+            if o.multi:
+                colon += "*-*:"  # every word up to the next option belongs to it
+            spec += f"{colon}{o.long.lstrip('-')}:{action}"
+        specs.append(f"  '{spec}'")
+    body = " \\\n".join(specs)
+    return f"""#compdef {PROG}
+# zsh completion for {PROG}
+# enable: eval "$({PROG} --completion zsh)"  (in ~/.zshrc, after compinit)
+_proxy_scraper() {{
+  _arguments -s \\
+{body}
+}}
+compdef _proxy_scraper {PROG}
+"""
+
+
+def _fish_quote(text: str) -> str:
+    return "'" + text.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def fish(opts: List[Option]) -> str:
+    lines = [f"# fish completion for {PROG}",
+             f"# enable: {PROG} --completion fish > ~/.config/fish/completions/{PROG}.fish",
+             f"complete -c {PROG} -f",
+             "# is the last option before the cursor $argv[1]? (for several values like --types http socks5)",
+             "function __proxy_scraper_after",
+             "    set -l tokens (commandline -opc)",
+             "    test (count $tokens) -gt 1; or return 1",
+             "    for token in $tokens[-1..2]",
+             "        string match -q -- '-*' $token; or continue",
+             "        test $token = $argv[1]; return",
+             "    end",
+             "    return 1",
+             "end"]
+    for o in opts:
+        parts = [f"complete -c {PROG}"]
+        if o.long:
+            parts.append(f"-l {o.long[2:]}")
+        if o.short:
+            parts.append(f"-s {o.short[1:]}")
+        if o.help:
+            parts.append(f"-d {_fish_quote(o.help)}")
+        if o.choices:
+            parts.append(f"-xa {_fish_quote(' '.join(o.choices))}")
+        elif o.is_file:
+            parts.append("-rF" + (f" -a {_fish_quote(' '.join(o.extra))}" if o.extra else ""))
+        elif o.takes_value and not o.optional_value:
+            parts.append("-x")
+        lines.append(" ".join(parts))
+        if o.multi and o.choices:
+            lines.append(f"complete -c {PROG} -n {_fish_quote('__proxy_scraper_after ' + o.long)} "
+                         f"-xa {_fish_quote(' '.join(o.choices))}")
+    return "\n".join(lines) + "\n"
+
+
+def script(parser: argparse.ArgumentParser, shell: str) -> str:
+    return {"bash": bash, "zsh": zsh, "fish": fish}[shell](options(parser))
+
+
+class CompletionAction(argparse.Action):
+    """--completion SHELL: print the script and exit – like --version, before anything starts."""
+
+    def __init__(self, option_strings, dest, **kwargs):
+        super().__init__(option_strings, dest, choices=SHELLS, **kwargs)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        sys.stdout.write(script(parser, values))
+        parser.exit()

proxyscraper/exporters.py

@@ -0,0 +1,118 @@
+"""Extra formats for common tools (--export).
+
+  proxychains   proxychains.conf with random_chain – ready to use with `proxychains4 -f`
+  clash         clash.yaml for Clash / Mihomo: proxies plus a url-test group
+                (both without HTTP proxies that can't CONNECT, see tunnels())
+  curl          curl.txt, one URL per line in the format for `curl -x` (SOCKS5 with DNS through the proxy)
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Callable, Dict, List, Sequence, Tuple
+
+from .checker import CheckResult
+from .handshake import parse_endpoint
+
+Exporter = Callable[[Sequence[CheckResult], datetime], str]
+
+
+def tunnels(r: CheckResult) -> bool:
+    """proxychains and Clash only talk to HTTP proxies via CONNECT. Whatever didn't pass the HTTPS test
+    usually can't do that – SOCKS always works, untested ones (--fast) stay in."""
+    return r.ptype != "http" or r.https is not False
+
+
+def proxychains(rows: Sequence[CheckResult], now: datetime) -> str:
+    entries = []
+    for r in rows:
+        ep = parse_endpoint(r.proxy)
+        creds = [ep.user, ep.password] if ep.has_auth else []
+        if not tunnels(r) or any(not c or c.split() != [c] for c in creds):
+            continue  # proxychains splits on spaces, empty fields don't work either
+        entries.append(" ".join([r.ptype, ep.host, str(ep.port), *creds]))
+    lines = [
+        f"# proxy-scraper, {now:%Y-%m-%d %H:%M}, {len(entries)} proxies (fastest first, HTTP only with CONNECT)",
+        "# usage: proxychains4 -f proxychains.conf curl https://api.ipify.org",
+        "random_chain",
+        "chain_len = 1",
+        "proxy_dns",
+        "tcp_read_time_out 15000",
+        "tcp_connect_time_out 8000",
+        "",
+        "[ProxyList]",
+    ]
+    return "\n".join(lines + entries) + "\n"
+
+
+CLASH_TYPES = {"http": "http", "socks5": "socks5"}  # Clash doesn't know SOCKS4
+
+
+def clash(rows: Sequence[CheckResult], now: datetime) -> str:
+    # JSON strings are valid YAML – so no YAML library is needed and nothing has to be escaped
+    q = json.dumps
+    usable = [r for r in rows if r.ptype in CLASH_TYPES and tunnels(r)]
+    names: List[str] = []
+    taken = set()
+    lines = [f"# proxy-scraper, {now:%Y-%m-%d %H:%M}, {len(usable)} proxies (Clash can't do SOCKS4)", "proxies:"]
+    for r in usable:
+        ep = parse_endpoint(r.proxy)
+        base = name = f"{r.country or '??'} {r.ptype} {ep.address}"
+        n = 1
+        while name in taken:  # the same proxy with different credentials
+            n += 1
+            name = f"{base} #{n}"
+        taken.add(name)
+        names.append(name)
+        lines += [
+            f"  - name: {q(name)}",
+            f"    type: {CLASH_TYPES[r.ptype]}",
+            f"    server: {q(ep.host)}",
+            f"    port: {ep.port}",
+        ]
+        if ep.has_auth:
+            lines += [f"    username: {q(ep.user)}", f"    password: {q(ep.password)}"]
+        if r.ptype == "socks5":
+            lines.append("    udp: false")
+    if not usable:
+        lines[-1] = "proxies: []"
+        return "\n".join(lines) + "\n"
+    lines += [
+        "proxy-groups:",
+        "  - name: proxy-scraper",
+        "    type: url-test",
+        "    url: http://www.gstatic.com/generate_204",
+        "    interval: 300",
+        "    tolerance: 100",
+        "    proxies:",
+        *(f"      - {q(n)}" for n in names),
+        "rules:",
+        "  - MATCH,proxy-scraper",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+CURL_SCHEMES = {"socks5": "socks5h", "socks4": "socks4", "http": "http"}
+
+
+def curl(rows: Sequence[CheckResult], now: datetime) -> str:
+    return "".join(f"{CURL_SCHEMES[r.ptype]}://{r.proxy}\n" for r in rows)
+
+
+EXPORTERS: Dict[str, Tuple[str, Exporter]] = {
+    "proxychains": ("proxychains.conf", proxychains),
+    "clash": ("clash.yaml", clash),
+    "curl": ("curl.txt", curl),
+}
+
+
+def parse_exports(value: str) -> List[str]:
+    """"clash,curl" -> ["clash", "curl"]; "all" -> all of them. Unknown names -> ValueError."""
+    names = [n.strip().lower() for n in value.split(",") if n.strip()]
+    unknown = [n for n in names if n not in EXPORTERS and n != "all"]
+    if unknown:  # check before "all" – otherwise a typo in "all,clsh" would go unnoticed
+        raise ValueError(f"unknown format: {', '.join(unknown)} (possible: {', '.join(EXPORTERS)}, all)")
+    if "all" in names:
+        return list(EXPORTERS)
+    return [n for n in EXPORTERS if n in names]  # fixed order, no duplicates