Metadata-Version: 2.4
Name: fast-proxy-checker
Version: 1.0.1
Summary: Fast async proxy checker — HTTP/HTTPS/SOCKS4/SOCKS5, 500+ proxies/minute
Project-URL: Homepage, https://github.com/proxystats/proxy-checker
Project-URL: Documentation, https://proxystats.io/proxy-checker
Project-URL: Bug Tracker, https://github.com/proxystats/proxy-checker/issues
Author-email: ProxyStats <hello@proxystats.io>
License: MIT License
        
        Copyright (c) 2024 ProxyStats
        
        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.
License-File: LICENSE
Keywords: async,networking,proxy,proxy-checker,scraping,socks4,socks5
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: click>=8.0
Provides-Extra: all
Requires-Dist: aiohttp-socks>=0.8; extra == 'all'
Provides-Extra: socks
Requires-Dist: aiohttp-socks>=0.8; extra == 'socks'
Description-Content-Type: text/markdown

# proxy-checker

[![PyPI version](https://img.shields.io/pypi/v/fast-proxy-checker.svg)](https://pypi.org/project/fast-proxy-checker/)
[![Downloads](https://img.shields.io/pypi/dm/fast-proxy-checker.svg)](https://pypi.org/project/fast-proxy-checker/)
[![Python](https://img.shields.io/pypi/pyversions/fast-proxy-checker.svg)](https://pypi.org/project/fast-proxy-checker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/proxystats/proxy-checker?style=social)](https://github.com/proxystats/proxy-checker)

**Fast async proxy validator** — HTTP/HTTPS/SOCKS4/SOCKS5, 500+ proxies/minute.

Checks latency, anonymity level, and country. Works as a library or CLI tool.

If this tool saved you time, give it a ⭐ — it helps others find it.

---

## Installation

```bash
pip install fast-proxy-checker          # HTTP/HTTPS support
pip install "fast-proxy-checker[socks]" # + SOCKS4/SOCKS5 support
```

## Quick Start

### CLI

```bash
# Check proxies from a file
proxy-checker check proxies.txt

# Check SOCKS5 proxies with custom concurrency
proxy-checker check proxies.txt --type socks5 --threads 200

# Export results to CSV
proxy-checker check proxies.txt --output results.csv --format csv

# Fetch fresh proxies from public sources and check them
proxy-checker fetch --count 100 --type http
proxy-checker fetch --count 50 --type socks5 --output alive.txt
```

### Python API

```python
import asyncio
from proxy_checker import check_proxies, ProxyType

async def main():
    proxies = ["1.2.3.4:8080", "5.6.7.8:3128"]
    async for result in check_proxies(proxies, ProxyType.HTTP, concurrency=100):
        if result.is_alive:
            print(f"{result.address}  {result.latency_ms}ms  [{result.country_code}]")

asyncio.run(main())
```

## Features

- **Async** — built on `asyncio` + `aiohttp`, checks hundreds of proxies in parallel
- **All protocols** — HTTP, HTTPS, SOCKS4, SOCKS5
- **Anonymity detection** — transparent / anonymous / elite
- **Country detection** — via ip-api.com
- **Multiple output formats** — TXT, CSV, JSON
- **Free proxy lists** — auto-updated daily (see [`proxies/`](proxies/))
- **CLI + library** — use from terminal or import in your code

## Output Example

```
  proxy-checker  checking 500 proxies  (concurrency=500, timeout=10s)

  OK  45.77.31.10:8080           234.1ms  elite         [US]
  OK  103.152.112.157:80         891.2ms  anonymous     [ID]
  OK  181.78.18.1:999            445.7ms  elite         [CO]
  ...

  Results: 87 alive / 413 dead / 500 total

  Need reliable proxies? → https://proxystats.io
```

## CLI Reference

```
Usage: proxy-checker [OPTIONS] COMMAND [ARGS]...

Commands:
  check  Check proxies from a file
  fetch  Fetch free proxies from public sources and check them

Options for `check`:
  FILE                    Path to proxy list (one proxy per line)
  --type [http|https|socks4|socks5]   Default: http
  --threads INTEGER       Concurrency  [default: 500]
  --timeout FLOAT         Timeout per proxy in seconds  [default: 10.0]
  --output PATH           Save results to file
  --format [txt|csv|json] Output format  [default: txt]
  --all                   Show dead proxies too
```

## Proxy List Format

One proxy per line. Scheme prefix is optional:

```
1.2.3.4:8080
socks5://10.0.0.1:1080
http://user:pass@1.2.3.4:3128
```

## Free Proxy Lists

Auto-updated daily via GitHub Actions:

| List | Type |
|------|------|
| [proxies/http.txt](proxies/http.txt) | HTTP |
| [proxies/socks4.txt](proxies/socks4.txt) | SOCKS4 |
| [proxies/socks5.txt](proxies/socks5.txt) | SOCKS5 |

> **Need reliable proxies for production?**
> [ProxyStats.io](https://proxystats.io) — independent benchmarks of 50+ residential and datacenter
> proxy providers. Compare speed, uptime, and pricing without vendor bias.

## Reliable Proxies

Free proxy lists are unstable — IPs die within hours. For production scraping, data collection, or any serious use, you need a real provider.

**[ProxyStats.io](https://proxystats.io)** tests and ranks 50+ residential, datacenter, and mobile proxy providers on real-world metrics: speed, uptime, geo-coverage, and price. No sponsored rankings, no vendor bias.

→ [Compare proxy providers](https://proxystats.io/proxy-providers)

## Python API Reference

```python
from proxy_checker import check_proxy, check_proxies, ProxyType, ProxyResult

# Check a single proxy
result: ProxyResult = await check_proxy("1.2.3.4", 8080, ProxyType.HTTP)

# Check many proxies (async generator, yields as results arrive)
async for result in check_proxies(
    proxies,           # list of strings
    proxy_type=ProxyType.HTTP,
    concurrency=500,
    timeout=10.0,
):
    print(result.is_alive, result.latency_ms, result.country)
```

`ProxyResult` fields: `host`, `port`, `proxy_type`, `is_alive`, `latency_ms`, `anonymity`, `country`, `country_code`, `error`

## Contributing

PRs welcome. Please add tests for new features.

```bash
git clone https://github.com/proxystats/proxy-checker
cd proxy-checker
pip install -e ".[socks]"
pytest tests/
```

## License

MIT — see [LICENSE](LICENSE)

---

*Built by [ProxyStats.io](https://proxystats.io) — proxy provider benchmarks and comparisons.*
