Metadata-Version: 2.4
Name: EasyProxies
Version: 3.0.1
Summary: A simple and quick way to get a proxy.
License: MIT
License-File: LICENSE
Author: Nikita Denissov
Author-email: n.denissov@proton.me
Requires-Python: >=3.8
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/ndenissov/EasyProxies
Project-URL: Repository, https://github.com/ndenissov/EasyProxies
Description-Content-Type: text/markdown

# EasyProxies

[![PyPI version](https://img.shields.io/pypi/v/EasyProxies.svg)](https://pypi.org/project/EasyProxies/)
[![Downloads](https://static.pepy.tech/badge/EasyProxies)](https://pepy.tech/project/EasyProxies)
[![Python versions](https://img.shields.io/pypi/pyversions/EasyProxies.svg)](https://pypi.org/project/EasyProxies/)
[![License](https://img.shields.io/pypi/l/EasyProxies.svg)](https://github.com/ndenissov/EasyProxies/blob/main/LICENSE)

A simple and fast library to interact with [proxyscan.io](https://web.archive.org/web/20230725025721/https://www.proxyscan.io/api) and proxyscan-like APIs to fetch free proxy servers.

---

## Features

* **Custom Host Support:** Easily override `BASE_URL` to point to any custom or mirror proxyscan-like API.
* **Flexible Formatting:** Support for both JSON (`ProxyDescriptor` objects) and TXT (`ip:port` strings) output formats.
* **Custom Headers:** Ships with configurable default HTTP headers (including a standard `User-Agent`).
* **Dynamic Generator:** Infinite proxy iterator with on-the-fly parameter updating.

---

## Installation

Install via pip:

```bash
pip install EasyProxies

```

Install via Poetry:

```bash
poetry add EasyProxies

```

---

## Quick Start

### Basic Usage & Custom Host Setup

If you need to route requests to a custom proxyscan-like backend, simply override `Proxies.BASE_URL`:

```python
from easy_proxies import Proxies, const

# Override base URL if needed
Proxies.BASE_URL = "https://your-custom-proxy-api.com"

# Fetch 20 proxies in text format (ip:port)
proxies = Proxies.get(limit=20, format='txt')
print(proxies)

```

### Integration with `requests`

By default (`format='json'`), `Proxies.get()` and `Proxies.best()` return `ProxyDescriptor` objects with helpful
conversion properties:

```python
import requests
from easy_proxies import Proxies

# Get the best proxy available
best_proxy = Proxies.best()

# Convert directly to a requests-compatible dictionary
proxies_dict = best_proxy.as_requests_proxy
print(f"Using proxy: {proxies_dict}")

try:
  response = requests.get("https://httpbin.org/ip", proxies=proxies_dict, timeout=10)
  print(response.json())
except requests.RequestException as e:
  print(f"Connection failed: {e}")

```

---

## CLI

```
EasyProxies --help
usage: EasyProxies [-h] [-f {json,txt}] [-l LIMIT] [--best] [-t {http,https,socks4,socks5} [{http,https,socks4,socks5} ...]]
                   [-a {transparent,anonymous,elite} [{transparent,anonymous,elite} ...]] [-c COUNTRY [COUNTRY ...]] [--not-country NOT_COUNTRY [NOT_COUNTRY ...]]
                   [--ping PING] [--uptime UPTIME]

Fetch proxy servers from proxyscan API via easy_proxies CLI.

optional arguments:
  -h, --help            show this help message and exit
  -f {json,txt}, --format {json,txt}
                        Output format: json (list of proxy objects) or txt (ip:port list). Default: json
  -l LIMIT, --limit LIMIT
                        Number of proxies to list (1-20). Default: 10
  --best                Fetch only the single best (fastest and most reliable) proxy.
  -t {http,https,socks4,socks5} [{http,https,socks4,socks5} ...], --type {http,https,socks4,socks5} [{http,https,socks4,socks5} ...]
                        Filter by proxy protocol(s).
  -a {transparent,anonymous,elite} [{transparent,anonymous,elite} ...], --level {transparent,anonymous,elite} [{transparent,anonymous,elite} ...]
                        Filter by anonymity level(s).
  -c COUNTRY [COUNTRY ...], --country COUNTRY [COUNTRY ...]
                        Filter by 2-letter country code(s), e.g., US FR.
  --not-country NOT_COUNTRY [NOT_COUNTRY ...]
                        Exclude 2-letter country code(s), e.g., CN NL.
  --ping PING           Maximum ping response time in ms.
  --uptime UPTIME       Minimum proxy uptime percentage (1-100).
  
```

---

## API Documentation

### Module Exports

```python
from easy_proxies import Proxies, ProxyDescriptor, DEFAULT_HEADERS, const

```

* `Proxies`: Main interface class for making API requests.
* `ProxyDescriptor`: Data class model wrapping proxy details.
* `DEFAULT_HEADERS`: Default headers dictionary used for HTTP requests (e.g., `{'User-Agent': 'Mozilla/5.0'}`).
* `const`: Constants for filtering parameters (`Format`, `Level`, `Type`, `Limit`, etc.).

---

### Class `Proxies`

An interface to communicate with the proxy provider.

#### Attributes:

* `BASE_URL`: `str` — Base target URL (defaults to `'https://www.proxyscan.io'`). Can be modified globally at runtime.

#### Methods:

* **`get(**kwargs) -> list[ProxyDescriptor | str] | str`**
  Fetches a list of proxies matching the specified filters.
* **`raw_request(param: dict[str, str | int]) -> list[ProxyDescriptor | str] | str`**
  Accepts a dictionary of raw query parameters instead of keyword arguments.
* **`already_list(type_: str) -> list[str]`**
  Returns a pre-assembled list of `ip:port` lines for a given protocol (`'http'`, `'socks5'`, etc.).
* **`best(**kwargs) -> ProxyDescriptor | str`**
  Returns the fastest and most reliable proxy server based on the query criteria.
* **`eternal_generator(**kwargs) -> Generator`**
  An infinite generator yielding proxies sequentially. Yields `None` when no proxies match. Parameters can be updated
  dynamically via `.send(new_params)`.

---

### Filtering Parameters (`kwargs` for `get` / `best`)

| Parameter     | Type / Allowed Values                       | Description                                             |
|---------------|---------------------------------------------|---------------------------------------------------------|
| `format`      | `'json'`, `'txt'`                           | Output format (JSON returns `ProxyDescriptor` objects). |
| `level`       | `'transparent'`, `'anonymous'`, `'elite'`   | Anonymity level.                                        |
| `type`        | `'http'`, `'https'`, `'socks4'`, `'socks5'` | Proxy protocols (supports single str or list/iterable). |
| `limit`       | `1` – `20`                                  | Max number of proxies to return.                        |
| `uptime`      | `1` – `100`                                 | Minimum reliability/uptime percentage.                  |
| `country`     | `str` or `list[str]` (e.g., `'US'`, `'FR'`) | Filter by country code(s).                              |
| `not_country` | `str` or `list[str]` (e.g., `'CN'`, `'NL'`) | Exclude specific country code(s).                       |
| `port`        | `int`                                       | Filter by a specific port number.                       |
| `ping`        | `int`                                       | Max response time (ping) in milliseconds.               |
| `last_check`  | `int`                                       | Max seconds since the last proxy check.                 |

---

### Structure of `ProxyDescriptor`

Represents detailed information about a single proxy server.

#### Key Attributes:

* `Ip`: `str` — IP address.
* `Port`: `str` — Port number.
* `Host`: `str` — Formatted as `ip:port`.
* `Ping`: `int` — Response latency in milliseconds.
* `Uptime`: `float` — Connection success rate ratio.
* `Anonymity`: `str` — Anonymity level.
* `Type`: `list[str]` — Supported protocols.
* `Location`: `Location` — Object containing geolocation data (`city`, `country`, `countryCode`, `isp`, etc.).

#### Properties & Features:

* `as_requests_proxy`: Returns `{'http': '...', 'https': '...'}` dictionary for `requests`/`httpx`.
* Rich comparisons: Supports native sorting (`<`, `>`, `==`) based on availability, ping, uptime, and anonymity.

---

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.

