EasyProxies

A simple and fast library to interact with proxyscan.io 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:

pip install EasyProxies

Install via Poetry:

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:

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:

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

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)

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.