proxmint 0.1.0__tar.gz

proxmint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proxmint
+
+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.

proxmint-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: proxmint
+Version: 0.1.0
+Summary: Free proxy list re-checked every 30 minutes, with rotating-proxy middleware for aiohttp and a rotating transport for httpx.
+Project-URL: Homepage, https://proxmint.com/docs/python
+Project-URL: Repository, https://github.com/proxmint/free-proxy-list
+Project-URL: Issues, https://github.com/proxmint/free-proxy-list/issues
+Author-email: Proxmint <support@proxmint.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aiohttp,free-proxy,httpx,proxies,proxy,proxy-list,rotating-proxy,socks5,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: aiohttp
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp>=3.12; extra == 'aiohttp'
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27; extra == 'httpx'
+Description-Content-Type: text/markdown
+
+# proxmint
+
+Free proxy list for Python, re-checked every 30 minutes, plus proxy rotation for aiohttp and httpx.
+The client has no dependencies and needs no API key or signup.
+
+Every proxy the API returns was proven alive by a real request made *through it* within the last half hour,
+not pinged and not assumed. Dead entries are dropped rather than left to rot.
+
+```bash
+pip install proxmint              # the client, standard library only
+pip install "proxmint[aiohttp]"   # + rotating-proxy middleware for aiohttp
+pip install "proxmint[httpx]"     # + rotating transports for httpx
+```
+
+## Free proxy list
+
+```python
+from proxmint import free_proxies, proxy_urls
+
+proxies = free_proxies(protocol="socks5", country="de", limit=50)
+# [{"ip": "203.0.113.7", "port": 1080, "protocol": "socks5", "countryCode": "de",
+#   "countryName": "Germany", "anonymity": "elite", "latencyMs": 412, "uptimePct": 97.5,
+#   "score": 91, "lastCheckedAt": "2026-10-28T10:56:12.583Z"}, ...]
+
+proxy_urls(sort="latency", limit=10)
+# ["http://198.51.100.4:3128", "socks5://203.0.113.7:1080", ...]
+```
+
+| Filter | |
+|---|---|
+| `protocol` | `http` · `https` · `socks4` · `socks5` |
+| `country` | ISO 3166-1 alpha-2, e.g. `de` |
+| `anonymity` | `elite` · `anonymous` · `transparent` |
+| `sort` | `score` (default) · `latency` · `uptime` · `checked` |
+| `limit` | rows wanted (default 20); paged past the API's 200-row cap |
+
+An `https` proxy is an HTTP proxy that can also tunnel TLS, so its URL starts with `http://`. `proxy_url(row)` builds
+the URL for one row. Failures raise `ProxmintError` with a `status`. The API allows 60 requests a minute per IP.
+
+## Rotating proxies with aiohttp
+
+```python
+import aiohttp
+from proxmint.aiohttp import RotatingProxy
+
+async with aiohttp.ClientSession(middlewares=(RotatingProxy(),)) as session:
+    async with session.get("https://example.com") as resp:
+        print(resp.status)
+```
+
+Each request goes out through the next proxy in the pool. A proxy that refuses the connection, times out, drops it or
+answers `407` is removed, and the request is retried through another, up to `tries=3` proxies. Each proxy gets
+`timeout=10` seconds to connect and send back headers. A session-wide `ClientTimeout(total=...)` covers all the tries
+together, so keep it loose.
+
+Without a list of your own, the pool is the 50 best `http` proxies on the free list, fetched again whenever it runs
+dry. The filters above narrow it: `RotatingProxy(country="us", sort="latency")`. To rotate through your own proxies,
+pass them: `RotatingProxy(["http://user:pass@203.0.113.7:3128", ...])`.
+
+Needs aiohttp 3.12 or later (client middleware). aiohttp speaks HTTP proxies only.
+
+## Rotating proxies with httpx
+
+```python
+import httpx
+from proxmint.httpx import AsyncRotatingTransport, RotatingTransport
+
+with httpx.Client(transport=RotatingTransport(country="us")) as client:
+    print(client.get("https://example.com").status_code)
+
+async with httpx.AsyncClient(transport=AsyncRotatingTransport()) as client:
+    print((await client.get("https://example.com")).status_code)
+```
+
+Same rotation and the same arguments. For SOCKS, `pip install "httpx[socks]"` and pass `protocol="socks5"` or your
+own `socks5://` URLs.
+
+Retries resend the request body, so a streamed upload can't be retried.
+
+## Warning
+
+These are free public proxies run by strangers. They are slow, short-lived, and some are honeypots that log or tamper
+with traffic. Use them for testing and research. **Never send logged-in or sensitive traffic through one.** We verify
+that a proxy forwards traffic, nothing more. We do not operate, audit or endorse any of them.
+
+Needing proxies that stay up is a different problem, and the one [Proxmint](https://proxmint.com) sells.
+
+## Also
+
+- Docs: <https://proxmint.com/docs/python>
+- Plain text and JSON files, committed every 30 minutes: [github.com/proxmint/free-proxy-list](https://github.com/proxmint/free-proxy-list)
+- HTTP API: <https://proxmint.com/free-proxies#api>
+- The same list from the command line: `npx proxmint`, or `sudo snap install proxmint`

proxmint-0.1.0/README.md

@@ -0,0 +1,93 @@
+# proxmint
+
+Free proxy list for Python, re-checked every 30 minutes, plus proxy rotation for aiohttp and httpx.
+The client has no dependencies and needs no API key or signup.
+
+Every proxy the API returns was proven alive by a real request made *through it* within the last half hour,
+not pinged and not assumed. Dead entries are dropped rather than left to rot.
+
+```bash
+pip install proxmint              # the client, standard library only
+pip install "proxmint[aiohttp]"   # + rotating-proxy middleware for aiohttp
+pip install "proxmint[httpx]"     # + rotating transports for httpx
+```
+
+## Free proxy list
+
+```python
+from proxmint import free_proxies, proxy_urls
+
+proxies = free_proxies(protocol="socks5", country="de", limit=50)
+# [{"ip": "203.0.113.7", "port": 1080, "protocol": "socks5", "countryCode": "de",
+#   "countryName": "Germany", "anonymity": "elite", "latencyMs": 412, "uptimePct": 97.5,
+#   "score": 91, "lastCheckedAt": "2026-10-28T10:56:12.583Z"}, ...]
+
+proxy_urls(sort="latency", limit=10)
+# ["http://198.51.100.4:3128", "socks5://203.0.113.7:1080", ...]
+```
+
+| Filter | |
+|---|---|
+| `protocol` | `http` · `https` · `socks4` · `socks5` |
+| `country` | ISO 3166-1 alpha-2, e.g. `de` |
+| `anonymity` | `elite` · `anonymous` · `transparent` |
+| `sort` | `score` (default) · `latency` · `uptime` · `checked` |
+| `limit` | rows wanted (default 20); paged past the API's 200-row cap |
+
+An `https` proxy is an HTTP proxy that can also tunnel TLS, so its URL starts with `http://`. `proxy_url(row)` builds
+the URL for one row. Failures raise `ProxmintError` with a `status`. The API allows 60 requests a minute per IP.
+
+## Rotating proxies with aiohttp
+
+```python
+import aiohttp
+from proxmint.aiohttp import RotatingProxy
+
+async with aiohttp.ClientSession(middlewares=(RotatingProxy(),)) as session:
+    async with session.get("https://example.com") as resp:
+        print(resp.status)
+```
+
+Each request goes out through the next proxy in the pool. A proxy that refuses the connection, times out, drops it or
+answers `407` is removed, and the request is retried through another, up to `tries=3` proxies. Each proxy gets
+`timeout=10` seconds to connect and send back headers. A session-wide `ClientTimeout(total=...)` covers all the tries
+together, so keep it loose.
+
+Without a list of your own, the pool is the 50 best `http` proxies on the free list, fetched again whenever it runs
+dry. The filters above narrow it: `RotatingProxy(country="us", sort="latency")`. To rotate through your own proxies,
+pass them: `RotatingProxy(["http://user:pass@203.0.113.7:3128", ...])`.
+
+Needs aiohttp 3.12 or later (client middleware). aiohttp speaks HTTP proxies only.
+
+## Rotating proxies with httpx
+
+```python
+import httpx
+from proxmint.httpx import AsyncRotatingTransport, RotatingTransport
+
+with httpx.Client(transport=RotatingTransport(country="us")) as client:
+    print(client.get("https://example.com").status_code)
+
+async with httpx.AsyncClient(transport=AsyncRotatingTransport()) as client:
+    print((await client.get("https://example.com")).status_code)
+```
+
+Same rotation and the same arguments. For SOCKS, `pip install "httpx[socks]"` and pass `protocol="socks5"` or your
+own `socks5://` URLs.
+
+Retries resend the request body, so a streamed upload can't be retried.
+
+## Warning
+
+These are free public proxies run by strangers. They are slow, short-lived, and some are honeypots that log or tamper
+with traffic. Use them for testing and research. **Never send logged-in or sensitive traffic through one.** We verify
+that a proxy forwards traffic, nothing more. We do not operate, audit or endorse any of them.
+
+Needing proxies that stay up is a different problem, and the one [Proxmint](https://proxmint.com) sells.
+
+## Also
+
+- Docs: <https://proxmint.com/docs/python>
+- Plain text and JSON files, committed every 30 minutes: [github.com/proxmint/free-proxy-list](https://github.com/proxmint/free-proxy-list)
+- HTTP API: <https://proxmint.com/free-proxies#api>
+- The same list from the command line: `npx proxmint`, or `sudo snap install proxmint`

proxmint-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "proxmint"
+version = "0.1.0"
+description = "Free proxy list re-checked every 30 minutes, with rotating-proxy middleware for aiohttp and a rotating transport for httpx."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Proxmint", email = "support@proxmint.com" }]
+keywords = ["proxy", "proxies", "free-proxy", "proxy-list", "rotating-proxy", "aiohttp", "httpx", "socks5", "web-scraping"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Framework :: AsyncIO",
+    "Framework :: aiohttp",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: Proxy Servers",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = []
+
+[project.optional-dependencies]
+aiohttp = ["aiohttp>=3.12"]
+httpx = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://proxmint.com/docs/python"
+Repository = "https://github.com/proxmint/free-proxy-list"
+Issues = "https://github.com/proxmint/free-proxy-list/issues"
+
+[dependency-groups]
+test = ["pytest>=8", "aiohttp>=3.12", "httpx>=0.27"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/proxmint"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

proxmint-0.1.0/src/proxmint/__init__.py

@@ -0,0 +1,141 @@
+"""Client for the Proxmint free proxy list, plus proxy rotation for aiohttp and httpx.
+
+Every proxy the API returns was proven alive by a real request made through it
+within the last 30 minutes: https://proxmint.com/free-proxies. No key, no signup.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__all__ = ["ProxmintError", "free_proxies", "proxy_url", "proxy_urls"]
+__version__ = "0.1.0"
+
+API = "https://proxmint.com/api/free-proxies"
+MAX_PAGE_SIZE = 200  # the server caps a page here, so larger requests are paged
+UA = f"proxmint-python/{__version__} (+https://proxmint.com/free-proxies)"
+
+
+class ProxmintError(Exception):
+    """The API refused or could not be reached; `status` is the HTTP status, if any."""
+
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+def free_proxies(
+    protocol: str | None = None,
+    country: str | None = None,
+    anonymity: str | None = None,
+    sort: str | None = None,
+    limit: int = 20,
+    timeout: float = 30,
+) -> list[dict]:
+    """Live proxies, best first, as dicts with ip, port, protocol, countryCode,
+    countryName, anonymity, latencyMs, uptimePct, score and lastCheckedAt.
+
+    protocol: "http", "https", "socks4" or "socks5". country: ISO 3166-1 alpha-2,
+    such as "de". anonymity: "elite", "anonymous" or "transparent". sort: "score"
+    (the default), "latency", "uptime" or "checked". limit is paged past the API's
+    200-row cap.
+    """
+    if not isinstance(limit, int) or isinstance(limit, bool) or limit < 1:
+        raise ValueError(f"limit must be a positive integer, got {limit!r}")
+    out: list[dict] = []
+    page = 1
+    while len(out) < limit:
+        query = {
+            "protocol": protocol,
+            "country": country.lower() if country else None,
+            "anonymity": anonymity,
+            "sort": sort,
+            "page": page,
+            "pageSize": min(limit - len(out), MAX_PAGE_SIZE),
+        }
+        url = f"{API}?{urllib.parse.urlencode({k: v for k, v in query.items() if v is not None})}"
+        req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": UA})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                body = json.load(resp)
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                raise ProxmintError("rate limited: the API allows 60 requests a minute per IP", 429) from None
+            raise ProxmintError(f"Proxmint API returned {e.code} {e.reason}", e.code) from None
+        except (urllib.error.URLError, TimeoutError) as e:
+            raise ProxmintError(f"could not reach the Proxmint API: {e}") from None
+        rows = body.get("rows") or []
+        out.extend(rows)
+        # A short page means the pool ended, not that the caller got what they asked for.
+        if not rows or len(out) >= (body.get("total") or 0):
+            break
+        page += 1
+    return out[:limit]
+
+
+def proxy_url(proxy: dict) -> str:
+    """The URL a client connects to for one row. An "https" proxy is an HTTP proxy
+    that can tunnel TLS with CONNECT, so it is reached over http://; an https:// URL
+    would make the client attempt TLS to the proxy itself."""
+    scheme = "http" if proxy["protocol"] == "https" else proxy["protocol"]
+    return f"{scheme}://{proxy['ip']}:{proxy['port']}"
+
+
+def proxy_urls(**filters) -> list[str]:
+    """`free_proxies(**filters)` as proxy URLs, best first."""
+    return [proxy_url(p) for p in free_proxies(**filters)]
+
+
+class _Pool:
+    """Round-robin over proxy URLs, shared by the aiohttp and httpx rotators. A proxy
+    that fails is dropped; an empty pool refills from the caller's list or, without
+    one, from a fresh fetch of the free list."""
+
+    def __init__(self, proxies, filters: dict):
+        self._fixed = None if proxies is None else [str(p) for p in proxies]
+        self._filters = {"protocol": "http", "limit": 50, **filters}
+        self._urls: list[str] = []
+        self._i = 0
+        self._lock = threading.Lock()
+        self._refilling = asyncio.Lock()
+
+    def refill(self) -> None:
+        urls = list(self._fixed) if self._fixed is not None else proxy_urls(**self._filters)
+        if not urls:
+            raise ProxmintError("no proxies to rotate through")
+        with self._lock:
+            self._urls, self._i = urls, 0
+
+    def _next(self) -> str | None:
+        with self._lock:
+            if not self._urls:
+                return None
+            self._i %= len(self._urls)
+            url = self._urls[self._i]
+            self._i += 1
+            return url
+
+    def take(self) -> str:
+        while (url := self._next()) is None:
+            self.refill()
+        return url
+
+    async def take_async(self) -> str:
+        while (url := self._next()) is None:
+            async with self._refilling:  # one fetch, however many requests found the pool empty
+                if not self._urls:
+                    await asyncio.to_thread(self.refill)
+        return url
+
+    def drop(self, url: str) -> None:
+        with self._lock:
+            if url in self._urls:
+                k = self._urls.index(url)
+                del self._urls[k]
+                if k < self._i:  # keep the cursor on the proxy that was next
+                    self._i -= 1

proxmint-0.1.0/src/proxmint/aiohttp.py

@@ -0,0 +1,52 @@
+"""aiohttp client middleware that sends each request through the next proxy in a pool."""
+
+from __future__ import annotations
+
+import asyncio
+
+import aiohttp
+from yarl import URL
+
+from . import _Pool
+
+# What a dead, blocked or tampering proxy looks like from aiohttp's side.
+PROXY_FAILURES = (aiohttp.ClientConnectionError, aiohttp.ClientHttpProxyError, asyncio.TimeoutError)
+
+
+class RotatingProxy:
+    """Client middleware (aiohttp 3.12+) that sends each request through the next
+    proxy in a pool. When a proxy fails, it is dropped and the request is retried
+    through another, up to `tries` proxies. Each proxy gets `timeout` seconds to
+    connect and answer with headers; a session-wide ClientTimeout(total=...) would
+    cover all the tries together, so one hanging proxy could use it up.
+
+        async with aiohttp.ClientSession(middlewares=(RotatingProxy(),)) as session:
+            async with session.get("https://example.com") as resp: ...
+
+    proxies: your own http:// proxy URLs, credentials included if they need them
+    (aiohttp has no SOCKS support). Without them the pool is the Proxmint free list,
+    filtered by `filters` (see `proxmint.free_proxies`; protocol defaults to "http")
+    and fetched again whenever it runs dry.
+    """
+
+    def __init__(self, proxies=None, *, tries: int = 3, timeout: float | None = 10, **filters):
+        self._pool = _Pool(proxies, filters)
+        self._tries = tries
+        self._timeout = timeout
+
+    async def __call__(self, req: aiohttp.ClientRequest, handler) -> aiohttp.ClientResponse:
+        for attempt in range(1, self._tries + 1):
+            proxy = await self._pool.take_async()
+            req.update_proxy(URL(proxy), None, req.proxy_headers)
+            try:
+                resp = await asyncio.wait_for(handler(req), self._timeout)
+            except PROXY_FAILURES:
+                self._pool.drop(proxy)
+                if attempt == self._tries:
+                    raise
+                continue
+            if resp.status != 407 or attempt == self._tries:
+                return resp
+            resp.release()  # the proxy wants credentials it was not given
+            self._pool.drop(proxy)
+        raise AssertionError("unreachable")

proxmint-0.1.0/src/proxmint/httpx.py

@@ -0,0 +1,88 @@
+"""httpx transports that send each request through the next proxy in a pool."""
+
+from __future__ import annotations
+
+import httpx
+
+from . import _Pool
+
+
+class RotatingTransport(httpx.BaseTransport):
+    """Sends each request through the next proxy in a pool. When a proxy fails, it
+    is dropped and the request is retried through another, up to `tries` proxies.
+
+        client = httpx.Client(transport=RotatingTransport())
+
+    proxies: your own proxy URLs, credentials included if they need them (socks5://
+    needs `httpx[socks]`). Without them the pool is the Proxmint free list, filtered
+    by `filters` (see `proxmint.free_proxies`; protocol defaults to "http") and
+    fetched again whenever it runs dry.
+    """
+
+    def __init__(self, proxies=None, *, tries: int = 3, **filters):
+        self._pool = _Pool(proxies, filters)
+        self._tries = tries
+        self._transports: dict[str, httpx.HTTPTransport] = {}
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        for attempt in range(1, self._tries + 1):
+            proxy = self._pool.take()
+            transport = self._transports.get(proxy) or self._transports.setdefault(proxy, httpx.HTTPTransport(proxy=proxy))
+            try:
+                response = transport.handle_request(request)
+            except httpx.TransportError:
+                self._drop(proxy)
+                if attempt == self._tries:
+                    raise
+                continue
+            if response.status_code != 407 or attempt == self._tries:
+                return response
+            response.close()  # the proxy wants credentials it was not given
+            self._drop(proxy)
+        raise AssertionError("unreachable")
+
+    def _drop(self, proxy: str) -> None:
+        self._pool.drop(proxy)
+        if (transport := self._transports.pop(proxy, None)) is not None:
+            transport.close()
+
+    def close(self) -> None:
+        for transport in self._transports.values():
+            transport.close()
+        self._transports.clear()
+
+
+class AsyncRotatingTransport(httpx.AsyncBaseTransport):
+    """`RotatingTransport` for `httpx.AsyncClient`."""
+
+    def __init__(self, proxies=None, *, tries: int = 3, **filters):
+        self._pool = _Pool(proxies, filters)
+        self._tries = tries
+        self._transports: dict[str, httpx.AsyncHTTPTransport] = {}
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        for attempt in range(1, self._tries + 1):
+            proxy = await self._pool.take_async()
+            transport = self._transports.get(proxy) or self._transports.setdefault(proxy, httpx.AsyncHTTPTransport(proxy=proxy))
+            try:
+                response = await transport.handle_async_request(request)
+            except httpx.TransportError:
+                await self._drop(proxy)
+                if attempt == self._tries:
+                    raise
+                continue
+            if response.status_code != 407 or attempt == self._tries:
+                return response
+            await response.aclose()
+            await self._drop(proxy)
+        raise AssertionError("unreachable")
+
+    async def _drop(self, proxy: str) -> None:
+        self._pool.drop(proxy)
+        if (transport := self._transports.pop(proxy, None)) is not None:
+            await transport.aclose()
+
+    async def aclose(self) -> None:
+        for transport in self._transports.values():
+            await transport.aclose()
+        self._transports.clear()

proxmint-0.1.0/tests/test_proxmint.py

@@ -0,0 +1,112 @@
+"""Offline checks: paging, URL schemes, and that both rotators drop a failing proxy
+and retry through the next one."""
+
+import asyncio
+import io
+import json
+import types
+import urllib.error
+import urllib.parse
+
+import aiohttp
+import httpx
+import pytest
+
+import proxmint
+import proxmint.aiohttp
+import proxmint.httpx
+
+
+def stub_api(monkeypatch, total, status=200):
+    """Serve a pool of `total` rows through urlopen; returns the queries made."""
+    calls = []
+
+    def urlopen(req, timeout):
+        q = dict(urllib.parse.parse_qsl(urllib.parse.urlsplit(req.full_url).query))
+        calls.append(q)
+        if status != 200:
+            raise urllib.error.HTTPError(req.full_url, status, "Nope", {}, None)
+        page, size = int(q["page"]), int(q["pageSize"])
+        start = (page - 1) * size
+        rows = [{"ip": f"10.0.0.{n % 256}", "port": 8080, "protocol": "http"} for n in range(start, min(start + size, total))]
+        return io.BytesIO(json.dumps({"rows": rows, "total": total}).encode())
+
+    monkeypatch.setattr(proxmint.urllib.request, "urlopen", urlopen)
+    return calls
+
+
+def test_pages_past_the_200_row_cap(monkeypatch):
+    calls = stub_api(monkeypatch, total=1000)
+    assert len(proxmint.free_proxies(limit=350)) == 350
+    assert [(c["page"], c["pageSize"]) for c in calls] == [("1", "200"), ("2", "150")]
+
+
+def test_stops_at_the_end_of_the_pool(monkeypatch):
+    calls = stub_api(monkeypatch, total=30)
+    assert len(proxmint.free_proxies(limit=500)) == 30
+    assert len(calls) == 1
+
+
+def test_bad_input_and_http_errors(monkeypatch):
+    calls = stub_api(monkeypatch, total=10, status=429)
+    with pytest.raises(ValueError):
+        proxmint.free_proxies(limit=0)
+    assert calls == []
+    with pytest.raises(proxmint.ProxmintError) as e:
+        proxmint.free_proxies(country="DE")
+    assert e.value.status == 429 and calls[0]["country"] == "de"
+
+
+def test_https_proxies_are_reached_over_http():
+    assert proxmint.proxy_url({"protocol": "https", "ip": "1.2.3.4", "port": 8080}) == "http://1.2.3.4:8080"
+    assert proxmint.proxy_url({"protocol": "socks5", "ip": "1.2.3.4", "port": 1080}) == "socks5://1.2.3.4:1080"
+
+
+DEAD, GOOD, AUTH, SLOW = "http://10.0.0.1:1", "http://10.0.0.2:2", "http://10.0.0.3:3", "http://10.0.0.4:4"
+
+
+class FakeTransport(httpx.BaseTransport):
+    def __init__(self, proxy):
+        self.proxy = str(proxy)
+
+    def handle_request(self, request):
+        if self.proxy == DEAD:
+            raise httpx.ConnectError("refused", request=request)
+        return httpx.Response(407 if self.proxy == AUTH else 200, text=self.proxy)
+
+
+def test_httpx_drops_failing_proxies_and_retries(monkeypatch):
+    monkeypatch.setattr(proxmint.httpx.httpx, "HTTPTransport", lambda proxy: FakeTransport(proxy))
+    with httpx.Client(transport=proxmint.httpx.RotatingTransport([DEAD, AUTH, GOOD])) as client:
+        assert client.get("http://example.com").text == GOOD  # dead, then 407, then good
+        assert client.get("http://example.com").text == GOOD  # only the good one is left
+    with httpx.Client(transport=proxmint.httpx.RotatingTransport([DEAD], tries=2)) as client:
+        with pytest.raises(httpx.ConnectError):
+            client.get("http://example.com")
+
+
+class FakeRequest:
+    proxy_headers = None
+
+    def update_proxy(self, proxy, auth, headers):
+        self.proxy = str(proxy)
+
+
+def test_aiohttp_drops_failing_proxies_and_retries():
+    async def handler(req):
+        if req.proxy == DEAD:
+            raise aiohttp.ServerDisconnectedError()
+        if req.proxy == SLOW:
+            await asyncio.sleep(5)
+        return types.SimpleNamespace(status=407 if req.proxy == AUTH else 200, proxy=req.proxy, release=lambda: None)
+
+    async def run():
+        mw = proxmint.aiohttp.RotatingProxy([DEAD, AUTH, GOOD])
+        assert (await mw(FakeRequest(), handler)).proxy == GOOD  # dead, then 407, then good
+        assert [(await mw(FakeRequest(), handler)).proxy for _ in range(2)] == [GOOD, GOOD]
+        slow_first = proxmint.aiohttp.RotatingProxy([SLOW, GOOD], timeout=0.05)
+        assert (await slow_first(FakeRequest(), handler)).proxy == GOOD  # a hang costs one timeout
+        with pytest.raises(aiohttp.ServerDisconnectedError):
+            await proxmint.aiohttp.RotatingProxy([DEAD], tries=2)(FakeRequest(), handler)
+
+    asyncio.run(run())