resolvekit 0.0.1__py3-none-any.whl

resolvekit/utils/errors.py

@@ -0,0 +1,145 @@
+"""Error classes for resolvekit."""
+
+
+class ResolvekitError(Exception):
+    """Base exception for all resolvekit errors."""
+
+    def __init__(self, message: str, details: dict | None = None):
+        """Initialize error with message and optional details."""
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        """String representation of error."""
+        if self.details:
+            details_str = ", ".join(f"{k}={v}" for k, v in self.details.items())
+            return f"{self.message} ({details_str})"
+        return self.message
+
+
+class ConfigError(ResolvekitError):
+    """Configuration error."""
+
+    pass
+
+
+class DataPackError(ResolvekitError):
+    """Data pack error (corrupt, missing, incompatible)."""
+
+    pass
+
+
+class ResolutionError(ResolvekitError):
+    """Resolution error."""
+
+    pass
+
+
+class ValidationError(ResolvekitError):
+    """Validation error."""
+
+    pass
+
+
+class OverlayError(ResolvekitError):
+    """Overlay error."""
+
+    pass
+
+
+class DatabaseError(ResolvekitError):
+    """Database error."""
+
+    pass
+
+
+class CalibrationError(ResolvekitError):
+    """Calibration error."""
+
+    pass
+
+
+class ExtractionError(ResolvekitError):
+    """Entity extraction error."""
+
+    pass
+
+
+class CodeFormatError(ValidationError):
+    """Code format validation error."""
+
+    def __init__(self, code: str, code_system: str, expected_format: str):
+        """Initialize code format error."""
+        super().__init__(
+            f"Invalid {code_system} code format: '{code}'. Expected format: {expected_format}",
+            details={"code": code, "system": code_system, "format": expected_format},
+        )
+
+
+class EntityNotFoundError(ResolutionError):
+    """Entity not found error."""
+
+    def __init__(self, query: str, min_confidence: float | None = None):
+        """Initialize entity not found error."""
+        msg = f"No entity found for query: '{query}'"
+        if min_confidence:
+            msg += f" (min_confidence={min_confidence})"
+        super().__init__(
+            msg, details={"query": query, "min_confidence": min_confidence}
+        )
+
+
+class AmbiguousQueryError(ResolutionError):
+    """Ambiguous query error when strict mode is enabled."""
+
+    def __init__(self, query: str, candidates: list[str]):
+        """Initialize ambiguous query error."""
+        super().__init__(
+            f"Ambiguous query: '{query}'. Multiple candidates: {', '.join(candidates[:5])}",
+            details={"query": query, "num_candidates": len(candidates)},
+        )
+
+
+class TemporalValidityError(ValidationError):
+    """Temporal validity error."""
+
+    def __init__(self, entity: str, date: str, reason: str):
+        """Initialize temporal validity error."""
+        super().__init__(
+            f"Entity '{entity}' not valid at date '{date}': {reason}",
+            details={"entity": entity, "date": date, "reason": reason},
+        )
+
+
+class HierarchyError(ValidationError):
+    """Hierarchy validation error."""
+
+    def __init__(self, child: str, parent: str, reason: str):
+        """Initialize hierarchy error."""
+        super().__init__(
+            f"Invalid hierarchy: '{child}' not a child of '{parent}': {reason}",
+            details={"child": child, "parent": parent, "reason": reason},
+        )
+
+
+class ChecksumMismatchError(DataPackError):
+    """Checksum mismatch error."""
+
+    def __init__(self, file_path: str, expected: str, actual: str):
+        """Initialize checksum mismatch error."""
+        super().__init__(
+            f"Checksum mismatch for '{file_path}'. Expected: {expected[:16]}..., Got: {actual[:16]}...",
+            details={"file": file_path, "expected": expected, "actual": actual},
+        )
+
+
+class IncompatibleVersionError(DataPackError):
+    """Incompatible version error."""
+
+    def __init__(self, component: str, required: str, found: str):
+        """Initialize incompatible version error."""
+        super().__init__(
+            f"Incompatible {component} version. Required: {required}, Found: {found}",
+            details={"component": component, "required": required, "found": found},
+        )

resolvekit/utils/files.py

@@ -0,0 +1,366 @@
+"""File utilities for resolvekit."""
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from resolvekit.utils.errors import ChecksumMismatchError, ValidationError
+
+
+def compute_checksum(
+    file_path: Path | str,
+    algorithm: str = "sha256",
+    chunk_size: int = 8192,
+) -> str:
+    """
+    Compute checksum of a file.
+
+    Args:
+        file_path: Path to file
+        algorithm: Hash algorithm (sha256, md5, sha1)
+        chunk_size: Chunk size for reading file
+
+    Returns:
+        Hex digest of checksum
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValidationError: If algorithm is unsupported
+
+    Examples:
+        >>> # compute_checksum("data.sqlite")
+        >>> # 'a3b2c1d4...'
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Get hash function
+    try:
+        hash_func = hashlib.new(algorithm)
+    except ValueError as e:
+        raise ValidationError(
+            f"Unsupported hash algorithm: {algorithm}",
+            details={"algorithm": algorithm},
+        ) from e
+
+    # Compute hash
+    with open(file_path, "rb") as f:
+        while chunk := f.read(chunk_size):
+            hash_func.update(chunk)
+
+    return hash_func.hexdigest()
+
+
+def verify_checksum(
+    file_path: Path | str,
+    expected_checksum: str,
+    algorithm: str = "sha256",
+    strict: bool = True,
+) -> bool:
+    """
+    Verify file checksum.
+
+    Args:
+        file_path: Path to file
+        expected_checksum: Expected checksum
+        algorithm: Hash algorithm
+        strict: If True, raise exception on mismatch
+
+    Returns:
+        True if checksum matches
+
+    Raises:
+        ChecksumMismatchError: If strict=True and checksum doesn't match
+    """
+    actual_checksum = compute_checksum(file_path, algorithm)
+
+    matches = actual_checksum == expected_checksum
+
+    if not matches and strict:
+        raise ChecksumMismatchError(str(file_path), expected_checksum, actual_checksum)
+
+    return matches
+
+
+def ensure_directory(dir_path: Path | str) -> Path:
+    """
+    Ensure directory exists, create if it doesn't.
+
+    Args:
+        dir_path: Directory path
+
+    Returns:
+        Path object for the directory
+    """
+    dir_path = Path(dir_path)
+    dir_path.mkdir(parents=True, exist_ok=True)
+    return dir_path
+
+
+def read_json(file_path: Path | str) -> Any:
+    """
+    Read JSON file.
+
+    Args:
+        file_path: Path to JSON file
+
+    Returns:
+        Parsed JSON data
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        json.JSONDecodeError: If JSON is invalid
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    with open(file_path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_json(
+    file_path: Path | str,
+    data: Any,
+    indent: int | None = 2,
+    ensure_dir: bool = True,
+) -> None:
+    """
+    Write data to JSON file.
+
+    Args:
+        file_path: Path to JSON file
+        data: Data to write
+        indent: Indentation level (None for compact)
+        ensure_dir: Create parent directories if they don't exist
+    """
+    file_path = Path(file_path)
+
+    if ensure_dir:
+        ensure_directory(file_path.parent)
+
+    with open(file_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=indent, ensure_ascii=False)
+
+
+def read_text(file_path: Path | str, encoding: str = "utf-8") -> str:
+    """
+    Read text file.
+
+    Args:
+        file_path: Path to text file
+        encoding: File encoding
+
+    Returns:
+        File contents as string
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    return file_path.read_text(encoding=encoding)
+
+
+def write_text(
+    file_path: Path | str,
+    content: str,
+    encoding: str = "utf-8",
+    ensure_dir: bool = True,
+) -> None:
+    """
+    Write text to file.
+
+    Args:
+        file_path: Path to text file
+        content: Text content
+        encoding: File encoding
+        ensure_dir: Create parent directories if they don't exist
+    """
+    file_path = Path(file_path)
+
+    if ensure_dir:
+        ensure_directory(file_path.parent)
+
+    file_path.write_text(content, encoding=encoding)
+
+
+def get_file_size(file_path: Path | str) -> int:
+    """
+    Get file size in bytes.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        File size in bytes
+    """
+    file_path = Path(file_path)
+    return file_path.stat().st_size
+
+
+def get_file_size_mb(file_path: Path | str) -> float:
+    """
+    Get file size in megabytes.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        File size in MB
+    """
+    return get_file_size(file_path) / (1024 * 1024)
+
+
+def list_files(
+    directory: Path | str,
+    pattern: str = "*",
+    recursive: bool = False,
+) -> list[Path]:
+    """
+    List files in directory matching pattern.
+
+    Args:
+        directory: Directory path
+        pattern: Glob pattern (e.g., "*.json", "**/*.sqlite")
+        recursive: Whether to search recursively
+
+    Returns:
+        List of matching file paths
+
+    Examples:
+        >>> # list_files("data/", "*.sqlite")
+        >>> # [Path('data/base.sqlite'), Path('data/overlay.sqlite')]
+    """
+    dir_path = Path(directory)
+
+    if not dir_path.exists():
+        return []
+
+    if recursive and "**" not in pattern:
+        pattern = f"**/{pattern}"
+
+    return sorted(dir_path.glob(pattern))
+
+
+def safe_remove(file_path: Path | str) -> bool:
+    """
+    Safely remove file if it exists.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        True if file was removed, False if it didn't exist
+    """
+    file_path = Path(file_path)
+
+    if file_path.exists():
+        file_path.unlink()
+        return True
+
+    return False
+
+
+def copy_file(src: Path | str, dst: Path | str, ensure_dir: bool = True) -> None:
+    """
+    Copy file from source to destination.
+
+    Args:
+        src: Source file path
+        dst: Destination file path
+        ensure_dir: Create destination directory if it doesn't exist
+    """
+    import shutil
+
+    src = Path(src)
+    dst = Path(dst)
+
+    if not src.exists():
+        raise FileNotFoundError(f"Source file not found: {src}")
+
+    if ensure_dir:
+        ensure_directory(dst.parent)
+
+    shutil.copy2(src, dst)
+
+
+def expand_path(path: Path | str) -> Path:
+    """
+    Expand user home directory and resolve path.
+
+    Args:
+        path: Path (may contain ~)
+
+    Returns:
+        Expanded and resolved path
+
+    Examples:
+        >>> # expand_path("~/.resolvekit/data")
+        >>> # Path('/home/user/.resolvekit/data')
+    """
+    return Path(path).expanduser().resolve()
+
+
+def get_manifest_checksums(directory: Path | str) -> dict[str, str]:
+    """
+    Compute checksums for all files in directory for manifest.
+
+    Args:
+        directory: Directory path
+
+    Returns:
+        Dictionary mapping filename to checksum
+
+    Examples:
+        >>> # get_manifest_checksums("data/")
+        >>> # {'base.sqlite': 'abc123...', 'calibration.json': 'def456...'}
+    """
+    directory = Path(directory)
+    checksums = {}
+
+    for file_path in directory.iterdir():
+        if file_path.is_file():
+            checksums[file_path.name] = compute_checksum(file_path)
+
+    return checksums
+
+
+def verify_manifest_checksums(
+    directory: Path | str,
+    checksums: dict[str, str],
+    strict: bool = True,
+) -> dict[str, bool]:
+    """
+    Verify checksums from manifest.
+
+    Args:
+        directory: Directory path
+        checksums: Dictionary mapping filename to expected checksum
+        strict: If True, raise exception on first mismatch
+
+    Returns:
+        Dictionary mapping filename to verification result
+
+    Raises:
+        ChecksumMismatchError: If strict=True and any checksum doesn't match
+    """
+    directory = Path(directory)
+    results = {}
+
+    for filename, expected_checksum in checksums.items():
+        file_path = directory / filename
+        try:
+            results[filename] = verify_checksum(
+                file_path, expected_checksum, strict=strict
+            )
+        except ChecksumMismatchError:
+            if strict:
+                raise
+            results[filename] = False
+
+    return results