proxywhirl.config

Configuration management for ProxyWhirl CLI.

This module handles TOML configuration discovery, loading, saving, and credential encryption for the CLI interface.

Classes

CLIConfig

Complete CLI configuration.

DataStorageConfig

Configuration for what data to persist to the database.

ProxyConfig

Configuration for a single proxy.

Functions

decrypt_credentials(config)

Decrypt all encrypted credential fields.

discover_config([explicit_path])

Discover configuration file location.

encrypt_credentials(config)

Encrypt all SecretStr fields in proxy configurations.

get_encryption_key(config)

Get or create the encryption key.

load_config([path])

Load and validate TOML configuration.

save_config(config, path)

Save configuration to TOML file with credential encryption.

Module Contents

class proxywhirl.config.CLIConfig(/, **data)[source]

Bases: pydantic.BaseModel

Complete CLI 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 Config[source]

Pydantic config.

classmethod validate_format(v)[source]

Validate output format.

Parameters:

v (str)

Return type:

str

classmethod validate_strategy(v)[source]

Validate rotation strategy.

Parameters:

v (str)

Return type:

str

class proxywhirl.config.DataStorageConfig(/, **data)[source]

Bases: pydantic.BaseModel

Configuration for what data to persist to the database.

All fields are configurable to allow users to: - Reduce storage by disabling less-critical fields - Improve privacy by opting out of geo/IP data - Balance performance vs analytics granularity

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 Config[source]

Pydantic config.

class proxywhirl.config.ProxyConfig(/, **data)[source]

Bases: pydantic.BaseModel

Configuration for a single 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_url(v)[source]

Validate proxy URL format.

Parameters:

v (str)

Return type:

str

proxywhirl.config.decrypt_credentials(config)[source]

Decrypt all encrypted credential fields.

Parameters:

config (CLIConfig) – Configuration with encrypted credentials

Returns:

Configuration with plain credentials

Return type:

CLIConfig

proxywhirl.config.discover_config(explicit_path=None)[source]

Discover configuration file location.

Parameters:

explicit_path (pathlib.Path | None) – User-provided config file path (highest priority)

Returns:

Path to config file, or None if not found

Return type:

pathlib.Path | None

Priority:

  1. Explicit path provided by user

  2. ./pyproject.toml (project-local)

  3. ~/.config/proxywhirl/config.toml (user-global)

  4. None (use defaults)

proxywhirl.config.encrypt_credentials(config)[source]

Encrypt all SecretStr fields in proxy configurations.

Parameters:

config (CLIConfig) – Configuration with plain credentials

Returns:

Configuration with encrypted credentials

Return type:

CLIConfig

proxywhirl.config.get_encryption_key(config)[source]

Get or create the encryption key.

Priority: 1. Environment variable (if set) 2. Persisted key file (~/.config/proxywhirl/key.enc) 3. Generate new key and persist it

Parameters:

config (CLIConfig) – CLI configuration

Returns:

Encryption key bytes

Return type:

bytes

proxywhirl.config.load_config(path=None)[source]

Load and validate TOML configuration.

Parameters:

path (pathlib.Path | None) – Path to config file (if None, uses defaults)

Returns:

Validated CLIConfig instance

Return type:

CLIConfig

proxywhirl.config.save_config(config, path)[source]

Save configuration to TOML file with credential encryption.

Parameters:
Return type:

None