pyplaykit 0.1.0__py3-none-any.whl

utils/data_validator.py

@@ -0,0 +1,426 @@
+"""Reusable data validation helpers for data, API, and UI output assertions."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timezone
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any
+
+
+class DataValidator:
+    """Assertion helpers for record-level and collection-level data checks."""
+
+    TRUE_STRINGS = {"true", "1", "yes", "y", "t"}
+    FALSE_STRINGS = {"false", "0", "no", "n", "f"}
+
+    @staticmethod
+    def assert_required_fields(record: dict[str, Any], required_fields: list[str]) -> None:
+        """Assert all required fields are present in record."""
+        missing = [field for field in required_fields if field not in record]
+        if missing:
+            raise AssertionError(f"Missing required fields: {missing}. Record: {record}")
+
+    @staticmethod
+    def assert_types(record: dict[str, Any], field_type_map: dict[str, type | tuple[type, ...]]) -> None:
+        """Assert each mapped field has expected type."""
+        for field, expected_type in field_type_map.items():
+            if field not in record:
+                raise AssertionError(f"Field '{field}' not found in record: {record}")
+            if not isinstance(record[field], expected_type):
+                raise AssertionError(
+                    f"Field '{field}' expected type {expected_type}, found {type(record[field])}."
+                )
+
+    @staticmethod
+    def assert_records_equal(
+        actual: dict[str, Any],
+        expected: dict[str, Any],
+        ignore_fields: set[str] | None = None,
+    ) -> None:
+        """Assert two records are equal after removing ignored top-level fields."""
+        ignored = ignore_fields or set()
+        normalized_actual = {k: v for k, v in actual.items() if k not in ignored}
+        normalized_expected = {k: v for k, v in expected.items() if k not in ignored}
+        if normalized_actual != normalized_expected:
+            raise AssertionError(
+                f"Record mismatch. Expected: {normalized_expected}, Actual: {normalized_actual}, Ignored: {ignored}"
+            )
+
+    @staticmethod
+    def assert_collection_contains_record(
+        records: list[dict[str, Any]],
+        expected_subset: dict[str, Any],
+    ) -> None:
+        """Assert at least one record contains all key/value pairs in expected subset."""
+        for record in records:
+            if all(record.get(key) == value for key, value in expected_subset.items()):
+                return
+        raise AssertionError(
+            f"No record matched expected subset: {expected_subset}. Records count: {len(records)}"
+        )
+
+    @staticmethod
+    def assert_boolean_like_equal(actual: Any, expected: Any) -> None:
+        """Assert values are equal after coercing common boolean-like inputs."""
+        actual_bool = DataValidator.to_bool(actual)
+        expected_bool = DataValidator.to_bool(expected)
+        if actual_bool != expected_bool:
+            raise AssertionError(
+                f"Boolean-like mismatch. Expected '{expected}' ({expected_bool}), found '{actual}' ({actual_bool})."
+            )
+
+    @staticmethod
+    def assert_floats_equal(
+        actual: Any,
+        expected: Any,
+        precision: int = 2,
+        tolerance: float | None = None,
+    ) -> None:
+        """Assert numeric values are equal by decimal precision or optional tolerance."""
+        actual_decimal = DataValidator._to_decimal(actual)
+        expected_decimal = DataValidator._to_decimal(expected)
+
+        if tolerance is not None:
+            if abs(actual_decimal - expected_decimal) > Decimal(str(tolerance)):
+                raise AssertionError(
+                    f"Float mismatch with tolerance {tolerance}. Expected '{expected}', found '{actual}'."
+                )
+            return
+
+        quantizer = Decimal("1").scaleb(-precision)
+        actual_quantized = actual_decimal.quantize(quantizer, rounding=ROUND_HALF_UP)
+        expected_quantized = expected_decimal.quantize(quantizer, rounding=ROUND_HALF_UP)
+        if actual_quantized != expected_quantized:
+            raise AssertionError(
+                f"Float mismatch at precision {precision}. Expected '{expected_quantized}', found '{actual_quantized}'."
+            )
+
+    @staticmethod
+    def normalize_string(
+        value: Any,
+        remove_special_chars: bool = True,
+        trim_spaces: bool = True,
+        collapse_spaces: bool = True,
+        case: str = "lower",
+    ) -> str:
+        """Normalize string for stable comparisons across formatting variations."""
+        normalized = "" if value is None else str(value)
+
+        # Preserve leading/trailing spaces if not trimming
+        leading_spaces = ""
+        trailing_spaces = ""
+        if not trim_spaces:
+            if isinstance(value, str):
+                leading_spaces = re.match(r"^\s*", value).group(0) if re.match(r"^\s*", value) else ""
+                trailing_spaces = re.search(r"\s*$", value).group(0) if re.search(r"\s*$", value) else ""
+            
+            # Temporarily trim for internal processing, re-add later
+            normalized = normalized.strip()
+
+
+        if remove_special_chars:
+            normalized = re.sub(r"[^\w\s]", " ", normalized)
+        if collapse_spaces:
+            normalized = re.sub(r"\s+", " ", normalized)
+        
+        # Apply trimming if requested
+        if trim_spaces:
+            normalized = normalized.strip()
+        
+        if case == "lower":
+            normalized = normalized.lower()
+        elif case == "upper":
+            normalized = normalized.upper()
+        elif case != "preserve":
+            raise ValueError("case must be one of: lower, upper, preserve")
+        
+        # Re-add leading/trailing spaces if not trimming was requested
+        if not trim_spaces:
+            normalized = leading_spaces + normalized + trailing_spaces
+
+        return normalized
+
+    @staticmethod
+    def assert_strings_equal_normalized(
+        actual: Any,
+        expected: Any,
+        remove_special_chars: bool = True,
+        trim_spaces: bool = True,
+        collapse_spaces: bool = True,
+        case: str = "lower",
+    ) -> None:
+        """Assert strings are equal after applying configurable normalization."""
+        actual_normalized = DataValidator.normalize_string(
+            actual,
+            remove_special_chars=remove_special_chars,
+            trim_spaces=trim_spaces,
+            collapse_spaces=collapse_spaces,
+            case=case,
+        )
+        expected_normalized = DataValidator.normalize_string(
+            expected,
+            remove_special_chars=remove_special_chars,
+            trim_spaces=trim_spaces,
+            collapse_spaces=collapse_spaces,
+            case=case,
+        )
+        if actual_normalized != expected_normalized:
+            raise AssertionError(
+                "String mismatch after normalization. "
+                f"Expected '{expected_normalized}', found '{actual_normalized}'."
+            )
+
+    @staticmethod
+    def assert_values_equal(
+        actual: Any,
+        expected: Any,
+        float_precision: int = 2,
+        float_tolerance: float | None = None,
+    ) -> None:
+        """Smart value assertion covering boolean-like, numeric, and string-like inputs."""
+        if DataValidator._is_boolean_like(actual) and DataValidator._is_boolean_like(expected):
+            DataValidator.assert_boolean_like_equal(actual, expected)
+            return
+
+        if DataValidator._is_number_like(actual) and DataValidator._is_number_like(expected):
+            DataValidator.assert_floats_equal(
+                actual,
+                expected,
+                precision=float_precision,
+                tolerance=float_tolerance,
+            )
+            return
+
+        DataValidator.assert_strings_equal_normalized(actual, expected)
+
+    @staticmethod
+    def unix_ticks_to_datetime(value: Any, unit: str = "auto", tz: timezone = UTC) -> datetime:
+        """Convert Unix ticks to timezone-aware datetime.
+
+        Supported units: seconds, milliseconds, microseconds, nanoseconds, auto.
+        """
+        ticks = float(DataValidator._to_decimal(value))
+        resolved_unit = DataValidator._resolve_unix_tick_unit(ticks, unit)
+        if resolved_unit == "seconds":
+            seconds = ticks
+        elif resolved_unit == "milliseconds":
+            seconds = ticks / 1_000
+        elif resolved_unit == "microseconds":
+            seconds = ticks / 1_000_000
+        elif resolved_unit == "nanoseconds":
+            seconds = ticks / 1_000_000_000
+        else:  # pragma: no cover
+            raise ValueError("unit must be one of: auto, seconds, milliseconds, microseconds, nanoseconds")
+        return datetime.fromtimestamp(seconds, UTC).astimezone(tz)
+
+    @staticmethod
+    def datetime_to_unix_ticks(value: Any, unit: str = "milliseconds") -> int | float:
+        """Convert datetime-like input to Unix ticks in the desired unit."""
+        dt_value = DataValidator._coerce_datetime(value)
+        epoch_seconds = dt_value.timestamp()
+        if unit == "seconds":
+            return epoch_seconds
+        if unit == "milliseconds":
+            return int(round(epoch_seconds * 1_000))
+        if unit == "microseconds":
+            return int(round(epoch_seconds * 1_000_000))
+        if unit == "nanoseconds":
+            return int(round(epoch_seconds * 1_000_000_000))
+        raise ValueError("unit must be one of: seconds, milliseconds, microseconds, nanoseconds")
+
+    @staticmethod
+    def parse_datetime(
+        value: Any,
+        input_formats: list[str] | None = None,
+        assume_tz: timezone = UTC,
+    ) -> datetime:
+        """Parse datetime input into UTC timezone-aware datetime."""
+        if isinstance(value, datetime):
+            parsed = value
+        elif DataValidator._is_number_like(value):
+            parsed = DataValidator.unix_ticks_to_datetime(value, unit="auto", tz=UTC)
+        elif isinstance(value, str):
+            text_value = value.strip()
+            try:
+                parsed = datetime.fromisoformat(text_value.replace("Z", "+00:00"))
+            except ValueError:
+                if not input_formats:
+                    raise ValueError(f"Unable to parse datetime value: '{value}'")
+                parsed = None
+                for fmt in input_formats:
+                    try:
+                        parsed = datetime.strptime(text_value, fmt)
+                        break
+                    except ValueError:
+                        continue
+                if parsed is None:
+                    raise ValueError(f"Unable to parse datetime value: '{value}'")
+        else:
+            raise ValueError(f"Unsupported datetime value: '{value}'")
+
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=assume_tz)
+        return parsed.astimezone(UTC)
+
+    @staticmethod
+    def assert_datetimes_equal(
+        actual: Any,
+        expected: Any,
+        tolerance_seconds: float = 0,
+        actual_unit: str = "auto",
+        expected_unit: str = "auto",
+    ) -> None:
+        """Assert two datetime-like values are equal within tolerance."""
+        actual_dt = DataValidator._coerce_datetime(actual, tick_unit=actual_unit)
+        expected_dt = DataValidator._coerce_datetime(expected, tick_unit=expected_unit)
+        delta_seconds = abs((actual_dt - expected_dt).total_seconds())
+        if delta_seconds > tolerance_seconds:
+            raise AssertionError(
+                "Datetime mismatch. "
+                f"Expected '{DataValidator.format_datetime_for_report(expected_dt)}', "
+                f"found '{DataValidator.format_datetime_for_report(actual_dt)}', "
+                f"delta={delta_seconds:.6f}s, tolerance={tolerance_seconds:.6f}s."
+            )
+
+    @staticmethod
+    def format_datetime_for_report(
+        value: Any,
+        input_unit: str = "auto",
+        output_format: str = "%Y-%m-%d %H:%M:%S.%f %Z",
+    ) -> str:
+        """Format datetime-like input into report-friendly UTC datetime text."""
+        dt_value = DataValidator._coerce_datetime(value, tick_unit=input_unit)
+        return dt_value.astimezone(UTC).strftime(output_format)
+
+    @staticmethod
+    def assert_record_datetime_fields(
+        actual_record: dict[str, Any],
+        expected_record: dict[str, Any],
+        field_rules: dict[str, dict[str, Any]],
+        default_tolerance_seconds: float = 0,
+        default_actual_unit: str = "auto",
+        default_expected_unit: str = "auto",
+    ) -> None:
+        """Compare datetime fields between two records using per-field rules.
+
+        field_rules example:
+        {
+            "created_at_ms": {
+                "expected_field": "created_at",
+                "actual_unit": "milliseconds",
+                "expected_unit": "auto",
+                "tolerance_seconds": 1,
+            }
+        }
+        """
+        if not field_rules:
+            raise ValueError("field_rules must include at least one datetime field rule")
+
+        errors: list[str] = []
+        for actual_field, rule in field_rules.items():
+            expected_field = rule.get("expected_field", actual_field)
+            actual_unit = rule.get("actual_unit", default_actual_unit)
+            expected_unit = rule.get("expected_unit", default_expected_unit)
+            tolerance_seconds = rule.get("tolerance_seconds", default_tolerance_seconds)
+
+            if actual_field not in actual_record:
+                errors.append(f"Actual record missing field '{actual_field}'")
+                continue
+            if expected_field not in expected_record:
+                errors.append(f"Expected record missing field '{expected_field}'")
+                continue
+
+            try:
+                DataValidator.assert_datetimes_equal(
+                    actual=actual_record[actual_field],
+                    expected=expected_record[expected_field],
+                    tolerance_seconds=tolerance_seconds,
+                    actual_unit=actual_unit,
+                    expected_unit=expected_unit,
+                )
+            except AssertionError as exc:
+                errors.append(f"{actual_field} vs {expected_field}: {exc}")
+
+        if errors:
+            joined = "; ".join(errors)
+            raise AssertionError(f"Datetime field validation failed: {joined}")
+
+    @staticmethod
+    def to_bool(value: Any) -> bool:
+        """Convert common boolean-like values into bool."""
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, (int, float)) and value in (0, 1):
+            return bool(value)
+        if isinstance(value, str):
+            cleaned = value.strip().lower()
+            if cleaned in DataValidator.TRUE_STRINGS:
+                return True
+            if cleaned in DataValidator.FALSE_STRINGS:
+                return False
+        raise ValueError(f"Unsupported boolean-like value: '{value}'")
+
+    @staticmethod
+    def _is_boolean_like(value: Any) -> bool:
+        if isinstance(value, bool):
+            return True
+        if isinstance(value, (int, float)) and value in (0, 1):
+            return True
+        if isinstance(value, str):
+            cleaned = value.strip().lower()
+            return cleaned in DataValidator.TRUE_STRINGS or cleaned in DataValidator.FALSE_STRINGS
+        return False
+
+    @staticmethod
+    def _is_number_like(value: Any) -> bool:
+        if isinstance(value, bool):
+            return False
+        if isinstance(value, (int, float, Decimal)):
+            return True
+        if isinstance(value, str):
+            try:
+                Decimal(value.strip())
+                return True
+            except Exception:
+                return False
+        return False
+
+    @staticmethod
+    def _to_decimal(value: Any) -> Decimal:
+        if isinstance(value, Decimal):
+            return value
+        if isinstance(value, bool):
+            raise ValueError("Boolean values are not supported for float conversion")
+        try:
+            return Decimal(str(value).strip())
+        except Exception as exc:
+            raise ValueError(f"Unsupported numeric value: '{value}'") from exc
+
+    @staticmethod
+    def _coerce_datetime(value: Any, tick_unit: str = "auto") -> datetime:
+        if isinstance(value, datetime):
+            parsed = value
+            if parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=UTC)
+            return parsed.astimezone(UTC)
+        if DataValidator._is_number_like(value):
+            return DataValidator.unix_ticks_to_datetime(value, unit=tick_unit, tz=UTC)
+        return DataValidator.parse_datetime(value)
+
+    @staticmethod
+    def _resolve_unix_tick_unit(ticks: float, unit: str) -> str:
+        valid_units = {"auto", "seconds", "milliseconds", "microseconds", "nanoseconds"}
+        if unit not in valid_units:
+            raise ValueError(f"unit must be one of: {', '.join(sorted(valid_units))}")
+
+        if unit != "auto":
+            return unit
+        absolute_ticks = abs(Decimal(str(ticks)))
+        if absolute_ticks >= Decimal('1e17'):
+            return "nanoseconds"
+        if absolute_ticks >= Decimal('1e14'):
+            return "microseconds"
+        if absolute_ticks >= Decimal('1e11'):
+            return "milliseconds"
+        return "seconds"

utils/environment_validator.py

@@ -0,0 +1,105 @@
+"""Environment readiness checks for URL/API availability and optional DB validation."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin
+from urllib.request import Request, urlopen
+
+
+def _check_url_availability(url: str, timeout_seconds: int) -> dict[str, str]:
+    request = Request(url=url, method="GET")
+    try:
+        with urlopen(request, timeout=timeout_seconds) as response:
+            return {
+                "name": "url_availability",
+                "status": "passed",
+                "details": f"URL reachable with status {response.getcode()}",
+            }
+    except HTTPError as exc:
+        return {
+            "name": "url_availability",
+            "status": "failed",
+            "details": f"HTTP error {exc.code}",
+        }
+    except URLError as exc:
+        return {
+            "name": "url_availability",
+            "status": "failed",
+            "details": f"URL error: {exc.reason}",
+        }
+
+
+def _check_api_health(base_url: str, health_endpoint: str, timeout_seconds: int) -> dict[str, str]:
+    health_url = urljoin(base_url.rstrip("/") + "/", health_endpoint.lstrip("/"))
+    request = Request(url=health_url, method="GET")
+    try:
+        with urlopen(request, timeout=timeout_seconds) as response:
+            status_code = response.getcode()
+            if status_code == 200:
+                return {
+                    "name": "api_health",
+                    "status": "passed",
+                    "details": f"Health endpoint responded with status {status_code}",
+                }
+            return {
+                "name": "api_health",
+                "status": "failed",
+                "details": f"Health endpoint returned status {status_code}",
+            }
+    except HTTPError as exc:
+        return {
+            "name": "api_health",
+            "status": "failed",
+            "details": f"Health endpoint HTTP error {exc.code}",
+        }
+    except URLError as exc:
+        return {
+            "name": "api_health",
+            "status": "failed",
+            "details": f"Health endpoint URL error: {exc.reason}",
+        }
+
+
+def _check_db_connectivity(db_check: Callable[[], tuple[bool, str]]) -> dict[str, str]:
+    try:
+        is_connected, details = db_check()
+        return {
+            "name": "db_connectivity",
+            "status": "passed" if is_connected else "failed",
+            "details": details,
+        }
+    except Exception as exc:
+        return {
+            "name": "db_connectivity",
+            "status": "failed",
+            "details": f"DB connectivity check failed: {exc}",
+        }
+
+
+def run_environment_readiness_checks(
+    base_url: str,
+    timeout_seconds: int = 5,
+    health_endpoint: str = "/health",
+    include_url_check: bool = True,
+    db_check: Callable[[], tuple[bool, str]] | None = None,
+) -> dict[str, Any]:
+    """Run configured readiness checks and return aggregate status."""
+    checks: list[dict[str, str]] = []
+
+    if include_url_check:
+        checks.append(_check_url_availability(base_url, timeout_seconds=timeout_seconds))
+
+    if health_endpoint:
+        checks.append(_check_api_health(base_url, health_endpoint=health_endpoint, timeout_seconds=timeout_seconds))
+
+    if db_check is not None:
+        checks.append(_check_db_connectivity(db_check))
+
+    failed_checks = [check for check in checks if check["status"] == "failed"]
+    return {
+        "ready": len(failed_checks) == 0,
+        "checks": checks,
+        "failed_checks": failed_checks,
+    }

utils/file_reader.py

@@ -0,0 +1,35 @@
+import json
+import configparser
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+def read_json_file(file_path: str) -> Dict[str, Any]:
+    """Reads a JSON file and returns its content as a dictionary."""
+    path = Path(file_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"JSON file not found: {file_path}")
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+def read_ini_file(file_path: str, section: Optional[str] = None, preserve_key_case: bool = False) -> Dict[str, Any]:
+    """
+    Reads an INI file and returns its content.
+    If section is provided, returns only that section.
+    If preserve_key_case is True, keys are case-sensitive.
+    """
+    path = Path(file_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"INI file not found: {file_path}")
+
+    config = configparser.ConfigParser()
+    if preserve_key_case:
+        config.optionxform = str # Preserve case for keys
+
+    config.read(file_path)
+
+    if section:
+        if section not in config:
+            raise KeyError(f"Section '{section}' not found in INI file: {file_path}")
+        return dict(config[section])
+    else:
+        return {s: dict(config[s]) for s in config.sections()}

utils/logger.py

@@ -0,0 +1,36 @@
+"""Framework logging utility with centralized setup."""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+
+def get_logger(
+    name: str = "pyplaykit",
+    log_file: str = "reports/framework.log",
+    level: int = logging.INFO,
+    fmt: Optional[str] = None,
+) -> logging.Logger:
+    """Return configured logger instance."""
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(level)
+    logger.propagate = False
+    Path(log_file).parent.mkdir(parents=True, exist_ok=True)
+
+    formatter = logging.Formatter(
+        fmt=fmt or "%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    file_handler = logging.FileHandler(log_file)
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    stream_handler = logging.StreamHandler()
+    stream_handler.setFormatter(formatter)
+    logger.addHandler(stream_handler)
+
+    return logger