EasyProxies

A simple and fast library to interact with the proxyscan.io API to fetch free proxy servers.

Installation

Install via pip:

pip install EasyProxies

Install via Poetry:

poetry add easyproxies

Quick Start

Fetching Proxies (TXT Format)

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

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:

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.

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.