proxywhirl.retry.executor

Retry execution orchestration with intelligent proxy selection.

Provides both synchronous and asynchronous retry execution: - execute_with_retry: Synchronous execution with time.sleep - execute_with_retry_async: Asynchronous execution with asyncio.sleep

The async variant avoids blocking the event loop during backoff delays.

Exceptions

NonRetryableError	Exception that does not trigger a retry.
RetryableError	Exception that triggers a retry.

Classes

RetryExecutor

Orchestrates retry logic with exponential backoff and circuit breaker integration.

Module Contents

exception proxywhirl.retry.executor.NonRetryableError

Bases: Exception

Exception that does not trigger a retry.

Initialize self. See help(type(self)) for accurate signature.

exception proxywhirl.retry.executor.RetryableError

Bases: Exception

Exception that triggers a retry.

Initialize self. See help(type(self)) for accurate signature.

class proxywhirl.retry.executor.RetryExecutor(retry_policy, circuit_breakers, retry_metrics)

Orchestrates retry logic with exponential backoff and circuit breaker integration.

Provides both synchronous and asynchronous execution methods: - execute_with_retry: Synchronous with time.sleep (for sync contexts) - execute_with_retry_async: Asynchronous with asyncio.sleep (for async contexts)

The async variant avoids blocking the event loop during backoff delays.

Initialize retry executor.

Parameters:

• retry_policy (proxywhirl.retry.policy.RetryPolicy) – Retry configuration

• circuit_breakers (dict[str, proxywhirl.circuit_breaker.CircuitBreaker]) – Circuit breakers by proxy ID

• retry_metrics (proxywhirl.retry.metrics.RetryMetrics) – Metrics collection instance

execute_with_retry(request_fn, proxy, method, url, request_id=None)

Execute a request with retry logic (SYNCHRONOUS).

This method uses time.sleep for backoff delays and should only be called from synchronous contexts. For async execution, use AsyncProxyClient._execute_async_with_retry instead.

Parameters:

• request_fn (collections.abc.Callable[[], httpx.Response]) – Function that executes the request

• proxy (proxywhirl.models.Proxy) – Initial proxy to use

• method (str) – HTTP method

• url (str) – Request URL

• request_id (str | None) – Optional request ID for tracking

Returns:

HTTP response

Raises:

• ProxyConnectionError – If all retries exhausted

• NonRetryableError – If error is not retryable

Return type:

httpx.Response

async execute_with_retry_async(request_fn, proxy, method, url, request_id=None)

Execute a request with retry logic (ASYNCHRONOUS).

This is the async variant of execute_with_retry that uses asyncio.sleep for non-blocking backoff delays instead of time.sleep.

Parameters:

• request_fn (collections.abc.Callable[[], collections.abc.Awaitable[httpx.Response]]) – Async function that executes the request

• proxy (proxywhirl.models.Proxy) – Initial proxy to use

• method (str) – HTTP method

• url (str) – Request URL

• request_id (str | None) – Optional request ID for tracking

Returns:

HTTP response

Raises:

• ProxyConnectionError – If all retries exhausted

• NonRetryableError – If error is not retryable

Return type:

httpx.Response

select_retry_proxy(available_proxies, failed_proxy, target_region=None)

Select best proxy for retry based on performance metrics.

Uses a weighted scoring formula: score = (0.7 ? success_rate) + (0.3 ? (1 - normalized_latency))

Parameters:

• available_proxies (list[proxywhirl.models.Proxy]) – List of available proxies

• failed_proxy (proxywhirl.models.Proxy) – The proxy that just failed

• target_region (str | None) – Optional target region for geo-targeted selection

Returns:

Best proxy for retry, or None if no suitable proxy found

Return type:

proxywhirl.models.Proxy | None