ffbb-data-client 2.0.0__py3-none-any.whl

ffbb_data_client/utils/converter_utils.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from datetime import datetime, time, timedelta, timezone
+from enum import Enum
+from typing import Any, TypeVar
+from uuid import UUID
+
+import dateutil.parser
+
+T = TypeVar("T")
+EnumT = TypeVar("EnumT", bound=Enum)
+
+logger = logging.getLogger(__name__)
+
+
+def from_officiels_list(x: Any) -> list | None:
+    """
+    Handle officiels field which can be either:
+    - A comma-separated string (old format)
+    - A list of dicts (new format)
+    - None
+    """
+    if x is None:
+        return None
+    if isinstance(x, list):
+        return x  # Return as-is if already a list
+    if isinstance(x, str):
+        return [s.strip() for s in x.split(",")] if x else None
+    return None
+
+
+# ---------------------------------------------------------------------------
+# from_TYPE helpers — direct dict-key extraction with type coercion
+# ---------------------------------------------------------------------------
+
+
+def from_str(obj: dict, key: str) -> str | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, str):
+        return x
+    try:
+        return str(x)
+    except (TypeError, ValueError):
+        logger.warning(
+            "from_str(%r): cannot convert %s to str (value: %.100r)",
+            key,
+            type(x).__name__,
+            x,
+        )
+        return None
+
+
+def from_int(obj: dict, key: str) -> int | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, int) and not isinstance(x, bool):
+        return x
+    if isinstance(x, str):
+        if not x.strip():
+            return None
+        try:
+            return int(x)
+        except ValueError:
+            logger.warning("from_int(%r): cannot parse %r as int", key, x)
+            return None
+    if isinstance(x, float):
+        return int(x)
+    logger.warning(
+        "from_int(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_float(obj: dict, key: str) -> float | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, (float, int)) and not isinstance(x, bool):
+        return float(x)
+    if isinstance(x, str):
+        try:
+            return float(x)
+        except ValueError:
+            logger.warning("from_float(%r): cannot parse %r as float", key, x)
+            return None
+    logger.warning(
+        "from_float(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_bool(obj: dict, key: str) -> bool | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, bool):
+        return x
+    if isinstance(x, str):
+        if x.lower() == "true":
+            return True
+        if x.lower() == "false":
+            return False
+        logger.warning("from_bool(%r): cannot parse %r as bool", key, x)
+        return None
+    logger.warning(
+        "from_bool(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_datetime(obj: dict, key: str) -> datetime | None:
+    x = obj.get(key)
+    if not x:
+        return None
+    if isinstance(x, str):
+        try:
+            # ⚡ Bolt optimization: datetime.fromisoformat is ~10x faster than dateutil.parser.parse
+            # We try the fast native ISO parsing first, then fallback to dateutil for complex formats
+            clean_str = x.replace("Z", "+00:00") if x.endswith("Z") else x
+            return datetime.fromisoformat(clean_str)
+        except ValueError:
+            try:
+                result: datetime = dateutil.parser.parse(x)
+                return result
+            except (ValueError, dateutil.parser.ParserError):
+                logger.warning("from_datetime(%r): cannot parse %r as datetime", key, x)
+                return None
+    logger.warning(
+        "from_datetime(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_time(obj: dict, key: str) -> time | None:
+    x = obj.get(key)
+    if not x:
+        return None
+    if isinstance(x, str):
+        # Format HH:MM:SS (Meilisearch)
+        if ":" in x:
+            parts = x.split(":")
+            try:
+                return time(
+                    int(parts[0]), int(parts[1]), int(parts[2]) if len(parts) > 2 else 0
+                )
+            except (ValueError, IndexError):
+                logger.warning("from_time(%r): cannot parse %r as time", key, x)
+                return None
+        # Format HHMM (REST API, 4-digit)
+        if x.isdigit() and len(x) == 4:
+            try:
+                return time(int(x[:2]), int(x[2:]))
+            except ValueError:
+                logger.warning("from_time(%r): cannot parse %r as time", key, x)
+                return None
+        logger.warning("from_time(%r): cannot parse %r as time", key, x)
+        return None
+    if isinstance(x, time):
+        return x
+    logger.warning(
+        "from_time(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_enum(enum_class: type[EnumT], obj: dict, key: str) -> EnumT | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    try:
+        return enum_class(x)
+    except ValueError:
+        logger.warning(
+            "from_enum(%s, %r): unknown value %r",
+            enum_class.__name__,
+            key,
+            x,
+        )
+        return None
+
+
+def from_obj(from_dict_fn: Callable[[Any], T], obj: dict, key: str) -> T | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, dict):
+        return from_dict_fn(x)
+    # Directus returns FK (str/int) when field depth is shallow (*),
+    # and the full object when depth is deep (*.*).
+    # Return None gracefully instead of warning for scalar FK values.
+    logger.debug(
+        "from_obj(%r): expected dict or None, got %s (scalar FK?)",
+        key,
+        type(x).__name__,
+    )
+    return None
+
+
+def from_list(item_fn: Callable[[Any], T], obj: dict, key: str) -> list[T] | None:
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, list):
+        return [item_fn(item) for item in x]
+    logger.warning(
+        "from_list(%r): expected list or None, got %s",
+        key,
+        type(x).__name__,
+    )
+    return None
+
+
+def from_uuid(obj: dict, key: str) -> UUID | None:
+    x = obj.get(key)
+    if not x:
+        return None
+    try:
+        return UUID(x) if isinstance(x, str) else None
+    except ValueError:
+        logger.warning("from_uuid(%r): invalid UUID %r", key, x)
+        return None
+
+
+def from_duration(obj: dict, key: str) -> timedelta | None:
+    """Parse a duration string like '37h00' or '6h55' into a timedelta.
+
+    Also handles numeric values (int/float) interpreted as hours,
+    and plain numeric strings.
+    """
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, timedelta):
+        return x
+    if isinstance(x, (int, float)):
+        return timedelta(hours=int(x), minutes=int((x % 1) * 60))
+    if isinstance(x, str):
+        x = x.strip()
+        if not x:
+            return None
+        # Format "37h00", "6h55", "10h50"
+        if "h" in x.lower():
+            parts = x.lower().split("h", 1)
+            try:
+                hours = int(parts[0])
+                minutes = int(parts[1]) if parts[1] else 0
+                return timedelta(hours=hours, minutes=minutes)
+            except ValueError:
+                logger.warning("from_duration(%r): cannot parse %r", key, x)
+                return None
+        # Plain numeric string → interpret as hours
+        try:
+            val = float(x)
+            return timedelta(hours=int(val), minutes=int((val % 1) * 60))
+        except ValueError:
+            logger.warning("from_duration(%r): cannot parse %r", key, x)
+            return None
+    logger.warning(
+        "from_duration(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_timestamp(obj: dict, key: str) -> datetime | None:
+    """Parse a Unix timestamp (int or numeric string) into a datetime (UTC)."""
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, (int, float)) and not isinstance(x, bool):
+        return datetime.fromtimestamp(x, tz=timezone.utc)
+    if isinstance(x, str):
+        x = x.strip()
+        if not x:
+            return None
+        try:
+            return datetime.fromtimestamp(int(x), tz=timezone.utc)
+        except (ValueError, OverflowError, OSError):
+            logger.warning("from_timestamp(%r): cannot parse %r as timestamp", key, x)
+            return None
+    logger.warning(
+        "from_timestamp(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None
+
+
+def from_phone(obj: dict, key: str) -> str | None:
+    """Parse a phone number string (normalized format)."""
+    x = obj.get(key)
+    if x is None:
+        return None
+    if isinstance(x, str):
+        if not x.strip():
+            return None
+        return x
+    if isinstance(x, (int, float)) and not isinstance(x, bool):
+        return str(int(x))
+    logger.warning(
+        "from_phone(%r): unexpected type %s (value: %.100r)",
+        key,
+        type(x).__name__,
+        x,
+    )
+    return None

ffbb_data_client/utils/input_validation.py

@@ -0,0 +1,360 @@
+"""
+Input validation utilities for FFBB Data Client.
+
+This module provides comprehensive validation functions for all input parameters
+to ensure data integrity and prevent common errors.
+"""
+
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+# Pre-compile regex patterns for performance (avoid redundant compilation in loops)
+_TOKEN_INVALID_CHARS_RE = re.compile(r'[<>"\';&]')
+_QUERY_INVALID_CHARS_RE = re.compile(r"[<>]")
+
+
+class ValidationError(ValueError):
+    """Exception raised when input validation fails."""
+
+
+def validate_token(token: str, field_name: str = "token") -> str:
+    """
+    Validate a bearer token.
+
+    Args:
+        token (str): The token to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        str: The validated token
+
+    Raises:
+        ValidationError: If token is invalid
+    """
+    if token is None:
+        raise ValidationError(f"{field_name} cannot be None")
+
+    if not isinstance(token, str):
+        raise ValidationError(
+            f"{field_name} must be a string, got {type(token).__name__}"
+        )
+
+    token_stripped = token.strip()
+    if not token_stripped:
+        raise ValidationError(f"{field_name} cannot be empty or whitespace-only")
+
+    if len(token_stripped) < 10:
+        raise ValidationError(f"{field_name} must be at least 10 characters long")
+
+    if len(token_stripped) > 1000:
+        raise ValidationError(f"{field_name} cannot be longer than 1000 characters")
+
+    # Check for potentially dangerous characters
+    # ⚡ Bolt optimization: using pre-compiled regex avoids recompilation overhead
+    if _TOKEN_INVALID_CHARS_RE.search(token_stripped):
+        raise ValidationError(f"{field_name} contains invalid characters")
+
+    return token_stripped
+
+
+def validate_url(url: str, field_name: str = "url") -> str:
+    """
+    Validate a URL.
+
+    Args:
+        url (str): The URL to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        str: The validated URL
+
+    Raises:
+        ValidationError: If URL is invalid
+    """
+    if url is None:
+        raise ValidationError(f"{field_name} cannot be None")
+
+    if not isinstance(url, str):
+        raise ValidationError(
+            f"{field_name} must be a string, got {type(url).__name__}"
+        )
+
+    url_stripped = url.strip()
+    if not url_stripped:
+        raise ValidationError(f"{field_name} cannot be empty")
+
+    # Parse URL
+    try:
+        parsed = urlparse(url_stripped)
+        if not parsed.scheme or not parsed.netloc:
+            raise ValidationError(f"{field_name} must be a valid URL")
+    except Exception as e:
+        raise ValidationError(f"{field_name} is not a valid URL: {e}") from e
+
+    # Check scheme
+    if parsed.scheme not in ["http", "https"]:
+        raise ValidationError(f"{field_name} must use HTTP or HTTPS protocol")
+
+    return url_stripped
+
+
+def validate_positive_integer(value: int | str, field_name: str = "value") -> int:
+    """
+    Validate a positive integer.
+
+    Args:
+        value: The value to validate (int or string representation)
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        int: The validated integer
+
+    Raises:
+        ValidationError: If value is invalid
+    """
+    if value is None:
+        raise ValidationError(f"{field_name} cannot be None")
+
+    try:
+        if isinstance(value, str):
+            int_value = int(value.strip())
+        else:
+            int_value = int(value)
+    except (ValueError, AttributeError) as e:
+        raise ValidationError(f"{field_name} must be a valid integer: {e}") from e
+
+    if int_value <= 0:
+        raise ValidationError(
+            f"{field_name} must be a positive integer, got {int_value}"
+        )
+
+    if int_value > 2**31 - 1:  # Max 32-bit signed integer
+        raise ValidationError(f"{field_name} is too large (max: {2**31 - 1})")
+
+    return int_value
+
+
+def validate_string_list(
+    values: list[str] | None, field_name: str = "values"
+) -> list[str] | None:
+    """
+    Validate a list of strings.
+
+    Args:
+        values: The list to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        Optional[List[str]]: The validated list or None
+
+    Raises:
+        ValidationError: If list is invalid
+    """
+    if values is None:
+        return None
+
+    if not isinstance(values, list):
+        raise ValidationError(
+            f"{field_name} must be a list, got {type(values).__name__}"
+        )
+
+    if len(values) == 0:
+        return values
+
+    validated_values = []
+    for i, value in enumerate(values):
+        if value is None:
+            raise ValidationError(f"{field_name}[{i}] cannot be None")
+
+        if not isinstance(value, str):
+            raise ValidationError(
+                f"{field_name}[{i}] must be a string, got {type(value).__name__}"
+            )
+
+        value_stripped = value.strip()
+        if not value_stripped:
+            raise ValidationError(f"{field_name}[{i}] cannot be empty")
+
+        if len(value_stripped) > 100:
+            raise ValidationError(f"{field_name}[{i}] is too long (max 100 characters)")
+
+        validated_values.append(value_stripped)
+
+    return validated_values
+
+
+def validate_boolean(value: Any, field_name: str = "value") -> bool:
+    """
+    Validate a boolean value.
+
+    Args:
+        value: The value to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        bool: The validated boolean
+
+    Raises:
+        ValidationError: If value is invalid
+    """
+    if isinstance(value, bool):
+        return value
+
+    if isinstance(value, str):
+        lower_value = value.lower().strip()
+        if lower_value in ["true", "1", "yes", "on"]:
+            return True
+        elif lower_value in ["false", "0", "no", "off"]:
+            return False
+
+    if isinstance(value, int):
+        if value == 0:
+            return False
+        elif value == 1:
+            return True
+
+    raise ValidationError(
+        f"{field_name} must be a boolean (True/False), got {value} ({type(value).__name__})"
+    )
+
+
+def validate_deep_limit(
+    deep_limit: str | int | None, field_name: str = "deep_limit"
+) -> str | None:
+    """
+    Validate a deep limit parameter.
+
+    Args:
+        deep_limit: The deep limit to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        Optional[str]: The validated deep limit or None
+
+    Raises:
+        ValidationError: If deep limit is invalid
+    """
+    if deep_limit is None:
+        return None
+
+    try:
+        if isinstance(deep_limit, str):
+            int_value = int(deep_limit.strip())
+        else:
+            int_value = int(deep_limit)
+    except (ValueError, AttributeError) as e:
+        raise ValidationError(f"{field_name} must be a valid integer: {e}") from e
+
+    if int_value < 1:
+        raise ValidationError(f"{field_name} must be at least 1, got {int_value}")
+
+    if int_value > 10000:
+        raise ValidationError(
+            f"{field_name} cannot be greater than 10000, got {int_value}"
+        )
+
+    return str(int_value)
+
+
+def validate_offset(value: int | str | None, field_name: str = "offset") -> int | None:
+    """
+    Validate an offset parameter (can be used for pagination).
+
+    Returns the integer offset or None.
+    """
+    if value is None:
+        return None
+
+    try:
+        if isinstance(value, str):
+            int_value = int(value.strip())
+        else:
+            int_value = int(value)
+    except (ValueError, AttributeError) as e:
+        raise ValidationError(f"{field_name} must be a valid integer: {e}") from e
+
+    if int_value < 0:
+        raise ValidationError(f"{field_name} must be >= 0, got {int_value}")
+
+    if int_value > 2**31 - 1:
+        raise ValidationError(f"{field_name} is too large (max: {2**31 - 1})")
+
+    return int_value
+
+
+def validate_filter_criteria(
+    filter_criteria: str | None, field_name: str = "filter_criteria"
+) -> str | None:
+    """
+    Validate filter criteria (JSON string).
+
+    Args:
+        filter_criteria: The filter criteria to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        Optional[str]: The validated filter criteria or None
+
+    Raises:
+        ValidationError: If filter criteria is invalid
+    """
+    if filter_criteria is None:
+        return None
+
+    if not isinstance(filter_criteria, str):
+        raise ValidationError(
+            f"{field_name} must be a string, got {type(filter_criteria).__name__}"
+        )
+
+    filter_stripped = filter_criteria.strip()
+    if not filter_stripped:
+        return None
+
+    if len(filter_stripped) > 1000:
+        raise ValidationError(f"{field_name} is too long (max 1000 characters)")
+
+    # Basic JSON structure validation
+    if not (filter_stripped.startswith("{") and filter_stripped.endswith("}")):
+        raise ValidationError(
+            f"{field_name} must be a valid JSON object (start with {{ and end with }})"
+        )
+
+    return filter_stripped
+
+
+def validate_search_query(query: str | None, field_name: str = "query") -> str | None:
+    """
+    Validate a search query.
+
+    Args:
+        query: The search query to validate
+        field_name (str): Name of the field for error messages
+
+    Returns:
+        Optional[str]: The validated query or None
+
+    Raises:
+        ValidationError: If query is invalid
+    """
+    if query is None:
+        return None
+
+    if not isinstance(query, str):
+        raise ValidationError(
+            f"{field_name} must be a string, got {type(query).__name__}"
+        )
+
+    query_stripped = query.strip()
+    if not query_stripped:
+        return None
+
+    if len(query_stripped) > 200:
+        raise ValidationError(f"{field_name} is too long (max 200 characters)")
+
+    # Check for potentially dangerous characters in search queries
+    # ⚡ Bolt optimization: using pre-compiled regex avoids recompilation overhead
+    if _QUERY_INVALID_CHARS_RE.search(query_stripped):
+        raise ValidationError(f"{field_name} contains invalid characters")
+
+    return query_stripped