ccproxy.core.validators

ccproxy.core.validators

Generic validation utilities for the CCProxy API.

ValidationError

Bases: Exception

Base class for validation errors.

validate_email

validate_email(email)

Validate email format.

Parameters:

Name	Type	Description	Default
email	str	Email address to validate	required

Returns:

Type	Description
str	The validated email address

Raises:

Type	Description
ValidationError	If email format is invalid

Source code in ccproxy/core/validators.py

def validate_email(email: str) -> str:
    """Validate email format.

    Args:
        email: Email address to validate

    Returns:
        The validated email address

    Raises:
        ValidationError: If email format is invalid
    """
    if not isinstance(email, str):
        raise ValidationError("Email must be a string")

    if not re.match(EMAIL_PATTERN, email):
        raise ValidationError(f"Invalid email format: {email}")

    return email.strip().lower()

validate_url

validate_url(url)

Validate URL format.

Parameters:

Name	Type	Description	Default
url	str	URL to validate	required

Returns:

Type	Description
str	The validated URL

Raises:

Type	Description
ValidationError	If URL format is invalid

Source code in ccproxy/core/validators.py

def validate_url(url: str) -> str:
    """Validate URL format.

    Args:
        url: URL to validate

    Returns:
        The validated URL

    Raises:
        ValidationError: If URL format is invalid
    """
    if not isinstance(url, str):
        raise ValidationError("URL must be a string")

    if not re.match(URL_PATTERN, url):
        raise ValidationError(f"Invalid URL format: {url}")

    try:
        parsed = urlparse(url)
        if not parsed.scheme or not parsed.netloc:
            raise ValidationError(f"Invalid URL format: {url}")
    except Exception as e:
        raise ValidationError(f"Invalid URL format: {url}") from e

    return url.strip()

validate_uuid

validate_uuid(uuid_str)

Validate UUID format.

Parameters:

Name	Type	Description	Default
uuid_str	str	UUID string to validate	required

Returns:

Type	Description
str	The validated UUID string

Raises:

Type	Description
ValidationError	If UUID format is invalid

Source code in ccproxy/core/validators.py

def validate_uuid(uuid_str: str) -> str:
    """Validate UUID format.

    Args:
        uuid_str: UUID string to validate

    Returns:
        The validated UUID string

    Raises:
        ValidationError: If UUID format is invalid
    """
    if not isinstance(uuid_str, str):
        raise ValidationError("UUID must be a string")

    if not re.match(UUID_PATTERN, uuid_str.lower()):
        raise ValidationError(f"Invalid UUID format: {uuid_str}")

    return uuid_str.strip().lower()

validate_path

validate_path(path, must_exist=True)

Validate file system path.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to validate	required
must_exist	bool	Whether the path must exist	True

Returns:

Type	Description
Path	The validated Path object

Raises:

Type	Description
ValidationError	If path is invalid

Source code in ccproxy/core/validators.py

def validate_path(path: str | Path, must_exist: bool = True) -> Path:
    """Validate file system path.

    Args:
        path: Path to validate
        must_exist: Whether the path must exist

    Returns:
        The validated Path object

    Raises:
        ValidationError: If path is invalid
    """
    if isinstance(path, str):
        path = Path(path)
    elif not isinstance(path, Path):
        raise ValidationError("Path must be a string or Path object")

    if must_exist and not path.exists():
        raise ValidationError(f"Path does not exist: {path}")

    return path.resolve()

validate_port

validate_port(port)

Validate port number.

Parameters:

Name	Type	Description	Default
port	int | str	Port number to validate	required

Returns:

Type	Description
int	The validated port number

Raises:

Type	Description
ValidationError	If port is invalid

Source code in ccproxy/core/validators.py

def validate_port(port: int | str) -> int:
    """Validate port number.

    Args:
        port: Port number to validate

    Returns:
        The validated port number

    Raises:
        ValidationError: If port is invalid
    """
    if isinstance(port, str):
        try:
            port = int(port)
        except ValueError as e:
            raise ValidationError(f"Port must be a valid integer: {port}") from e

    if not isinstance(port, int):
        raise ValidationError(f"Port must be an integer: {port}")

    if port < 1 or port > 65535:
        raise ValidationError(f"Port must be between 1 and 65535: {port}")

    return port

validate_timeout

validate_timeout(timeout)

Validate timeout value.

Parameters:

Name	Type	Description	Default
timeout	float | int | str	Timeout value to validate	required

Returns:

Type	Description
float	The validated timeout value

Raises:

Type	Description
ValidationError	If timeout is invalid

Source code in ccproxy/core/validators.py

def validate_timeout(timeout: float | int | str) -> float:
    """Validate timeout value.

    Args:
        timeout: Timeout value to validate

    Returns:
        The validated timeout value

    Raises:
        ValidationError: If timeout is invalid
    """
    if isinstance(timeout, str):
        try:
            timeout = float(timeout)
        except ValueError as e:
            raise ValidationError(f"Timeout must be a valid number: {timeout}") from e

    if not isinstance(timeout, int | float):
        raise ValidationError(f"Timeout must be a number: {timeout}")

    if timeout < 0:
        raise ValidationError(f"Timeout must be non-negative: {timeout}")

    return float(timeout)

validate_non_empty_string

validate_non_empty_string(value, name='value')

Validate that a string is not empty.

Parameters:

Name	Type	Description	Default
value	str	String value to validate	required
name	str	Name of the field for error messages	'value'

Returns:

Type	Description
str	The validated string

Raises:

Type	Description
ValidationError	If string is empty or not a string

Source code in ccproxy/core/validators.py

def validate_non_empty_string(value: str, name: str = "value") -> str:
    """Validate that a string is not empty.

    Args:
        value: String value to validate
        name: Name of the field for error messages

    Returns:
        The validated string

    Raises:
        ValidationError: If string is empty or not a string
    """
    if not isinstance(value, str):
        raise ValidationError(f"{name} must be a string")

    if not value.strip():
        raise ValidationError(f"{name} cannot be empty")

    return value.strip()

validate_dict

validate_dict(value, required_keys=None)

Validate dictionary and required keys.

Parameters:

Name	Type	Description	Default
value	Any	Value to validate as dictionary	required
required_keys	list[str] | None	List of required keys	None

Returns:

Type	Description
dict[str, Any]	The validated dictionary

Raises:

Type	Description
ValidationError	If not a dictionary or missing required keys

Source code in ccproxy/core/validators.py

def validate_dict(value: Any, required_keys: list[str] | None = None) -> dict[str, Any]:
    """Validate dictionary and required keys.

    Args:
        value: Value to validate as dictionary
        required_keys: List of required keys

    Returns:
        The validated dictionary

    Raises:
        ValidationError: If not a dictionary or missing required keys
    """
    if not isinstance(value, dict):
        raise ValidationError("Value must be a dictionary")

    if required_keys:
        missing_keys = [key for key in required_keys if key not in value]
        if missing_keys:
            raise ValidationError(f"Missing required keys: {missing_keys}")

    return value

validate_list

validate_list(value, min_length=0, max_length=None)

Validate list and length constraints.

Parameters:

Name	Type	Description	Default
value	Any	Value to validate as list	required
min_length	int	Minimum list length	0
max_length	int | None	Maximum list length	None

Returns:

Type	Description
list[Any]	The validated list

Raises:

Type	Description
ValidationError	If not a list or length constraints are violated

Source code in ccproxy/core/validators.py

def validate_list(
    value: Any, min_length: int = 0, max_length: int | None = None
) -> list[Any]:
    """Validate list and length constraints.

    Args:
        value: Value to validate as list
        min_length: Minimum list length
        max_length: Maximum list length

    Returns:
        The validated list

    Raises:
        ValidationError: If not a list or length constraints are violated
    """
    if not isinstance(value, list):
        raise ValidationError("Value must be a list")

    if len(value) < min_length:
        raise ValidationError(f"List must have at least {min_length} items")

    if max_length is not None and len(value) > max_length:
        raise ValidationError(f"List cannot have more than {max_length} items")

    return value

validate_choice

validate_choice(value, choices, name='value')

Validate that value is one of the allowed choices.

Parameters:

Name	Type	Description	Default
value	Any	Value to validate	required
choices	list[Any]	List of allowed choices	required
name	str	Name of the field for error messages	'value'

Returns:

Type	Description
Any	The validated value

Raises:

Type	Description
ValidationError	If value is not in choices

Source code in ccproxy/core/validators.py

def validate_choice(value: Any, choices: list[Any], name: str = "value") -> Any:
    """Validate that value is one of the allowed choices.

    Args:
        value: Value to validate
        choices: List of allowed choices
        name: Name of the field for error messages

    Returns:
        The validated value

    Raises:
        ValidationError: If value is not in choices
    """
    if value not in choices:
        raise ValidationError(f"{name} must be one of {choices}, got: {value}")

    return value

validate_range

validate_range(
    value, min_value=None, max_value=None, name="value"
)

Validate that a numeric value is within a specified range.

Parameters:

Name	Type	Description	Default
value	float | int	Numeric value to validate	required
min_value	float | int | None	Minimum allowed value	None
max_value	float | int | None	Maximum allowed value	None
name	str	Name of the field for error messages	'value'

Returns:

Type	Description
float | int	The validated value

Raises:

Type	Description
ValidationError	If value is outside the allowed range

Source code in ccproxy/core/validators.py

def validate_range(
    value: float | int,
    min_value: float | int | None = None,
    max_value: float | int | None = None,
    name: str = "value",
) -> float | int:
    """Validate that a numeric value is within a specified range.

    Args:
        value: Numeric value to validate
        min_value: Minimum allowed value
        max_value: Maximum allowed value
        name: Name of the field for error messages

    Returns:
        The validated value

    Raises:
        ValidationError: If value is outside the allowed range
    """
    if not isinstance(value, int | float):
        raise ValidationError(f"{name} must be a number")

    if min_value is not None and value < min_value:
        raise ValidationError(f"{name} must be at least {min_value}")

    if max_value is not None and value > max_value:
        raise ValidationError(f"{name} must be at most {max_value}")

    return value