Python API Usage & Examples

Relevant source files

The following files were used as context for generating this wiki page:

• proxybroker/api.py
• examples/basic.py
• examples/find_and_use.py
• README.md
• CLAUDE.md
• tests/test_api.py
• tests/test_integration.py

ProxyBroker2 provides a high-level asynchronous Python API to find, check, and use public proxies. The API revolves around the Broker class, which orchestrates discovery from providers and validation through checkers. Developers use this API to integrate proxy discovery directly into Python applications using asyncio.

Sources: README.md:162-164, CLAUDE.md:73-77, tests/test_api.py:15-18

Core API Components

The system consists of several interoperable classes that manage the proxy lifecycle from discovery to rotation in a local server.

The Broker Class

The Broker acts as the central orchestrator. It manages the pipeline by connecting providers, which find raw proxy data, to checkers, which validate the proxies against judge servers.

Sources: CLAUDE.md:73-76, tests/test_api.py:23-56

Proxy Objects

A Proxy object represents a single discovered endpoint. It contains metadata including the host, port, supported protocols, anonymity level, and performance statistics like average response time.

Sources: CLAUDE.md:126-130, tests/test_integration.py:46-51, tests/test_api.py:108-111

Relationship Diagram

The following diagram shows the relationship between core API components during a typical discovery session.

Common Workflows

Finding and Validating Proxies

The find() method discovers proxies and validates them. You provide a list of desired protocols and an optional limit. The method populates a provided asyncio.Queue with working Proxy objects.

async def main():
    proxies = asyncio.Queue()
    broker = Broker(proxies)
    await asyncio.gather(
        broker.find(types=["HTTP", "HTTPS"], limit=10),
        show(proxies)
    )

Sources: README.md:214-230, tests/test_api.py:73-83

Grabbing Proxies Without Validation

The grab() method fetches proxies from providers without performing health checks or anonymity detection. This method is faster but does not guarantee proxy functionality.

async def grab_proxies():
    proxies = asyncio.Queue()
    broker = Broker(proxies)
    await broker.grab(countries=['US'], limit=20)

Sources: tests/test_api.py:58-71, tests/test_integration.py:126-140, CLAUDE.md:74

Discovery Flow

The following sequence diagram illustrates the internal flow when calling broker.find().

Configuration Options

The Broker constructor accepts several parameters to tune performance and behavior.

Parameter	Type	Default	Description
queue	asyncio.Queue	None	Queue to populate with found proxies
timeout	int	8	Connection timeout in seconds
max_conn	int	200	Maximum concurrent connections
max_tries	int	3	Maximum attempts to check a proxy
judges	list	None	List of custom judge URLs
providers	list	None	List of custom provider URLs or objects
verify_ssl	bool	False	Verify SSL certificates during checks

Sources: tests/test_integration.py:157-167, tests/test_api.py:27-51, CLAUDE.md:80-84

Data Export and Representation

Proxy objects provide standard methods to export data for storage or display.

• as_json(): Returns a dictionary containing host, port, geolocation data, supported types, average response time, and error rate.
• as_text(): Returns a string in the standard host:port\n format, suitable for writing directly to proxy list files.

# JSON Output Structure
{
    "host": "8.8.8.8",
    "port": 3128,
    "geo": {"code": "US", "name": "United States"},
    "types": [{"type": "HTTP", "level": "Anonymous"}],
    "avg_resp_time": 1.5,
    "error_rate": 0.0
}

Sources: tests/test_integration.py:64-83, tests/test_api.py:108-124

Resource Management

The Broker manages asynchronous resources and signal handlers. You must call broker.stop() to properly remove signal handlers and prevent memory leaks. When using the serve() method, the returned server object should be stopped using server.stop() or await server.aclose().

Sources: CLAUDE.md:143-144, tests/test_api.py:128-138, tests/test_integration.py:20-22