proxywhirl.api.models

API-specific Pydantic models for REST API request/response validation.

This module contains models specific to the HTTP API layer, separate from core domain models in models.py. These models define the API contract including: - Generic response envelope (APIResponse[T]) - Error details and codes - Request/response metadata - API-specific entities (ProxyResource, etc.)

Classes

APIResponse	Generic envelope for all API responses.
CircuitBreakerEventResponse	Response model for circuit breaker state change event.
CircuitBreakerResponse	Response model for circuit breaker state.
ConfigurationSettings	API configuration settings.
CreateProxyRequest	Request to add a new proxy to the pool.
ErrorCode	Standard error codes for API responses.
ErrorDetail	Structured error information for API responses.
ExportHistoryResponse	Response model for export history query.
ExportRequest	Request model for creating an export.
ExportStatusResponse	Response model for export status query.
HealthCheckRequest	Request to health check specific proxies.
HealthCheckResult	Result of a proxy health check.
HealthResponse	API health status response.
MetaInfo	Metadata included in all API responses.
MetricsResponse	API performance metrics response.
PaginatedResponse	Paginated list response.
ProxiedRequest	Request to make an HTTP request through a proxy.
ProxiedResponse	Response from a proxied HTTP request.
ProxyMetrics	Per-proxy performance metrics.
ProxyPoolStats	Statistics about the proxy pool.
ProxyResource	RESTful representation of a proxy in the pool.
ProxyRetryStats	Per-proxy retry statistics.
ProxyRetryStatsResponse	Response model for per-proxy retry statistics.
ProxyStats	Per-proxy statistics for metrics endpoints.
RateLimitConfig	Rate limiting configuration.
ReadinessResponse	API readiness status response.
RetryMetricsResponse	Response model for retry metrics summary.
RetryPolicyRequest	Request model for updating retry policy.
RetryPolicyResponse	Response model for retry policy.
StatusResponse	API and pool status response.
TimeSeriesDataPoint	Single data point in time-series metrics.
TimeSeriesResponse	Response model for time-series retry data.
UpdateConfigRequest	Request to update API configuration (partial updates allowed).

Module Contents

class proxywhirl.api.models.APIResponse(/, **data)

Bases: pydantic.BaseModel, Generic[T]

Generic envelope for all API responses.

Provides consistent structure: - status: HTTP-like status indicator - data: Successful response payload (type T) - error: Error details if request failed - meta: Request metadata (ID, timestamp, version)

Example successful response:

{
    "status": "success",
    "data": {"id": "123", "url": "http://proxy:8080"},
    "error": null,
    "meta": {"request_id": "...", "timestamp": "...", "version": "1.0.0"}
}

Example error response:

{
    "status": "error",
    "data": null,
    "error": {"code": "PROXY_NOT_FOUND", "message": "...", ...},
    "meta": {"request_id": "...", "timestamp": "...", "version": "1.0.0"}
}

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

classmethod error_response(code, message, details=None, **kwargs)

Create an error response with error details.

Parameters:

• code (ErrorCode) – Machine-readable error code

• message (str) – Human-readable error message

• details (dict[str, Any] | None) – Additional error context

• **kwargs (Any) – Additional fields to override (e.g., meta)

Returns:

APIResponse with status=’error’ and error populated

Return type:

APIResponse[T]

classmethod success(data, **kwargs)

Create a successful response with data payload.

Parameters:

• data (T) – Response payload

• **kwargs (Any) – Additional fields to override (e.g., meta)

Returns:

APIResponse with status=’success’ and data populated

Return type:

APIResponse[T]

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.CircuitBreakerEventResponse(/, **data)

Bases: pydantic.BaseModel

Response model for circuit breaker state change event.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.CircuitBreakerResponse(/, **data)

Bases: pydantic.BaseModel

Response model for circuit breaker state.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ConfigurationSettings(/, **data)

Bases: pydantic.BaseModel

API configuration settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.CreateProxyRequest(/, **data)

Bases: pydantic.BaseModel

Request to add a new proxy to the pool.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

classmethod validate_proxy_url(v)

Validate proxy URL scheme, port, and length.

Parameters:

v (str) – Proxy URL to validate

Returns:

Validated URL

Raises:

ValueError – If URL is invalid

Return type:

str

classmethod validate_username(v)

Validate username length.

Parameters:

v (str | None) – Username to validate

Returns:

Validated username

Raises:

ValueError – If username exceeds length limit

Return type:

str | None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ErrorCode

Bases: str, enum.Enum

Standard error codes for API responses.

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

class proxywhirl.api.models.ErrorDetail(/, **data)

Bases: pydantic.BaseModel

Structured error information for API responses.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ExportHistoryResponse(/, **data)

Bases: pydantic.BaseModel

Response model for export history query.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ExportRequest(/, **data)

Bases: pydantic.BaseModel

Request model for creating an export.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ExportStatusResponse(/, **data)

Bases: pydantic.BaseModel

Response model for export status query.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.HealthCheckRequest(/, **data)

Bases: pydantic.BaseModel

Request to health check specific proxies.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.HealthCheckResult(/, **data)

Bases: pydantic.BaseModel

Result of a proxy health check.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.HealthResponse(/, **data)

Bases: pydantic.BaseModel

API health status response.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.MetaInfo(/, **data)

Bases: pydantic.BaseModel

Metadata included in all API responses.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.MetricsResponse(/, **data)

Bases: pydantic.BaseModel

API performance metrics response.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.PaginatedResponse(/, **data)

Bases: pydantic.BaseModel, Generic[T]

Paginated list response.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ProxiedRequest(/, **data)

Bases: pydantic.BaseModel

Request to make an HTTP request through a proxy.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

classmethod validate_body(v)

Validate body length.

Parameters:

v (str | None) – Body string to validate

Returns:

Validated body

Raises:

ValueError – If body exceeds length limit

Return type:

str | None

classmethod validate_headers(v)

Validate header names and values length.

Parameters:

v (dict[str, str]) – Headers dict to validate

Returns:

Validated headers

Raises:

ValueError – If header name or value exceeds length limit

Return type:

dict[str, str]

classmethod validate_url_scheme(v)

Validate that URL uses http or https scheme only.

Parameters:

v (pydantic.HttpUrl) – URL to validate

Returns:

Validated URL

Raises:

ValueError – If URL scheme is not http or https

Return type:

pydantic.HttpUrl

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ProxiedResponse(/, **data)

Bases: pydantic.BaseModel

Response from a proxied HTTP request.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ProxyMetrics(/, **data)

Bases: pydantic.BaseModel

Per-proxy performance metrics.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class proxywhirl.api.models.ProxyPoolStats(/, **data)

Bases: pydantic.BaseModel

Statistics about the proxy pool.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class proxywhirl.api.models.ProxyResource(/, **data)

Bases: pydantic.BaseModel

RESTful representation of a proxy in the pool.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ProxyRetryStats(/, **data)

Bases: pydantic.BaseModel

Per-proxy retry statistics.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ProxyRetryStatsResponse(/, **data)

Bases: pydantic.BaseModel

Response model for per-proxy retry statistics.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.ProxyStats(/, **data)

Bases: pydantic.BaseModel

Per-proxy statistics for metrics endpoints.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class proxywhirl.api.models.RateLimitConfig(/, **data)

Bases: pydantic.BaseModel

Rate limiting configuration.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class proxywhirl.api.models.ReadinessResponse(/, **data)

Bases: pydantic.BaseModel

API readiness status response.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.RetryMetricsResponse(/, **data)

Bases: pydantic.BaseModel

Response model for retry metrics summary.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.RetryPolicyRequest(/, **data)

Bases: pydantic.BaseModel

Request model for updating retry policy.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.RetryPolicyResponse(/, **data)

Bases: pydantic.BaseModel

Response model for retry policy.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.StatusResponse(/, **data)

Bases: pydantic.BaseModel

API and pool status response.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.TimeSeriesDataPoint(/, **data)

Bases: pydantic.BaseModel

Single data point in time-series metrics.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class proxywhirl.api.models.TimeSeriesResponse(/, **data)

Bases: pydantic.BaseModel

Response model for time-series retry data.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class proxywhirl.api.models.UpdateConfigRequest(/, **data)

Bases: pydantic.BaseModel

Request to update API configuration (partial updates allowed).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

classmethod validate_cors_origins(v)

Validate CORS origins length.

Parameters:

v (list[str] | None) – CORS origins to validate

Returns:

Validated CORS origins

Raises:

ValueError – If any origin exceeds length limit

Return type:

list[str] | None

classmethod validate_rotation_strategy(v)

Validate rotation strategy is from allowed set.

Parameters:

v (str | None) – Rotation strategy to validate

Returns:

Validated rotation strategy

Raises:

ValueError – If rotation strategy is invalid

Return type:

str | None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].