Metadata-Version: 2.4
Name: EasyProxies
Version: 2.0.2
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.9
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

A simple and fast library to interact with the [proxyscan.io](https://www.proxyscan.io/) API to fetch free proxy
servers.

---

## Installation

Install via pip:

```bash
pip install EasyProxies
```

Install via Poetry:

```bash
poetry add easyproxies
```

---

## Quick Start

### Fetching Proxies (TXT Format)

Get a list of 20 proxies as `ip:port` strings:

```python
from EasyProxies import Proxies, const

# Get 20 proxies in text format
proxies = Proxies.get(limit=20, format='txt')
for proxy in proxies:
    print(proxy)
```

### Integration with `requests`

If `format='json'` (default), the library returns a list of `ProxyDescriptor` objects. You can use their helper
properties to configure HTTP clients:

```python
import requests
from EasyProxies import Proxies

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

# Use the as_requests_proxy helper property
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}")
```

---

## API Documentation

### Class `Proxies`

An interface to communicate with the proxy provider.

#### Methods:

* **`get(**kwargs) -> list[ProxyDescriptor | str]`**
  Fetches a list of proxies matching the specified filters.

* **`raw_request(param: dict[str, str | int]) -> list[ProxyDescriptor | str]`**
  Performs the same function as `get`, but accepts a dictionary of parameters.

* **`already_list(type_: str) -> list[str]`**
  Returns a pre-assembled list of `ip:port` proxies for a specific protocol (e.g., `'http'`).

* **`best(**kwargs) -> ProxyDescriptor`**
  Returns the fastest and most reliable proxy server found using the specified parameters.

* **`eternal_generator(**kwargs) -> Generator`**
  An infinite generator for proxies. Yields `None` if no proxies are found matching the filters. Parameters can be
  updated dynamically by passing a dictionary to the generator's `.send()` method.

---

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

You can pass string values directly or use type-safe classes from `EasyProxies.const`.

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

---

### Structure of `ProxyDescriptor`

Represents a detailed representation of a proxy server returned in `json` format.

#### Attributes:

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

#### Properties and Methods:

* `as_requests_proxy` — Returns a dictionary compatible with the `requests` library `proxies` parameter.
* Supports sorting and comparison based on failure state, ping latency, uptime, and anonymity level.

---

## License

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

