coding-client 1.21.2__py3-none-any.whl

coding_client/utils/encoding_helper.py

@@ -0,0 +1,222 @@
+"""
+Encoding helper utilities for handling text encoding/decoding.
+
+This module centralizes encoding operations to reduce cyclomatic complexity
+across services that handle file content (github_integration_service, etc.).
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Default encoding fallback chain
+DEFAULT_ENCODINGS: list[str] = ["utf-8", "latin-1", "cp1252", "iso-8859-1"]
+
+
+def decode_with_fallback(
+    content: bytes,
+    encodings: list[str] | None = None,
+    errors: str = "strict",
+    log_fallback: bool = True,
+) -> tuple[str, str]:
+    """
+    Decode bytes to string, trying multiple encodings.
+
+    Args:
+        content: Bytes to decode
+        encodings: List of encodings to try (default: utf-8, latin-1, cp1252, iso-8859-1)
+        errors: Error handling mode for final attempt ('strict', 'replace', 'ignore')
+        log_fallback: Whether to log when falling back to non-utf8 encoding
+
+    Returns:
+        Tuple of (decoded_string, encoding_used)
+
+    Raises:
+        UnicodeDecodeError: If all encodings fail and errors='strict'
+
+    Example:
+        # Instead of:
+        # try:
+        #     content = content.decode("utf-8")
+        # except UnicodeDecodeError:
+        #     for encoding in ["latin-1", "cp1252", "iso-8859-1"]:
+        #         try:
+        #             content = content.decode(encoding)
+        #             break
+        #         except UnicodeDecodeError:
+        #             continue
+
+        # Use:
+        content, encoding = decode_with_fallback(raw_bytes)
+    """
+    if encodings is None:
+        encodings = DEFAULT_ENCODINGS.copy()
+
+    last_error: UnicodeDecodeError | None = None
+
+    for encoding in encodings:
+        try:
+            decoded = content.decode(encoding)
+            if encoding != "utf-8" and log_fallback:
+                logger.debug(f"Decoded content using fallback encoding: {encoding}")
+            return decoded, encoding
+        except UnicodeDecodeError as e:
+            last_error = e
+            continue
+
+    # If all encodings failed, try with error handling
+    if errors != "strict":
+        try:
+            decoded = content.decode("utf-8", errors=errors)
+            logger.warning(f"Decoded content with error handling mode: {errors}")
+            return decoded, f"utf-8-{errors}"
+        except UnicodeDecodeError:
+            pass
+
+    # Raise the last error if nothing worked
+    if last_error:
+        raise last_error
+    raise UnicodeDecodeError("utf-8", content, 0, len(content), "All encodings failed")
+
+
+def decode_safe(
+    content: bytes,
+    encodings: list[str] | None = None,
+    default: str = "",
+) -> str:
+    """
+    Safely decode bytes to string, returning default on failure.
+
+    Args:
+        content: Bytes to decode
+        encodings: List of encodings to try
+        default: Value to return if decoding fails
+
+    Returns:
+        Decoded string or default
+
+    Example:
+        content = decode_safe(raw_bytes, default="<binary content>")
+    """
+    try:
+        decoded, _ = decode_with_fallback(content, encodings, errors="replace")
+        return decoded
+    except Exception:
+        return default
+
+
+def encode_safe(
+    content: str,
+    encoding: str = "utf-8",
+    errors: str = "replace",
+) -> bytes:
+    """
+    Safely encode string to bytes with error handling.
+
+    Args:
+        content: String to encode
+        encoding: Target encoding
+        errors: Error handling mode ('strict', 'replace', 'ignore', 'xmlcharrefreplace')
+
+    Returns:
+        Encoded bytes
+
+    Example:
+        # Instead of:
+        # content = content.encode("utf-8", errors="replace").decode("utf-8")
+        # Use:
+        safe_bytes = encode_safe(content)
+    """
+    return content.encode(encoding, errors=errors)
+
+
+def normalize_to_utf8(content: str | bytes) -> str:
+    """
+    Normalize content to UTF-8 string, handling both bytes and strings.
+
+    Args:
+        content: String or bytes to normalize
+
+    Returns:
+        UTF-8 normalized string
+
+    Example:
+        text = normalize_to_utf8(possibly_bytes_or_string)
+    """
+    if isinstance(content, bytes):
+        decoded, _ = decode_with_fallback(content, errors="replace")
+        return decoded
+    return content.encode("utf-8", errors="replace").decode("utf-8")
+
+
+def is_binary_content(content: bytes, sample_size: int = 8192) -> bool:
+    """
+    Detect if content appears to be binary (non-text).
+
+    Args:
+        content: Bytes to check
+        sample_size: Number of bytes to sample for detection
+
+    Returns:
+        True if content appears to be binary
+
+    Example:
+        if is_binary_content(file_bytes):
+            logger.info("Skipping binary file")
+    """
+    # Check for null bytes (common indicator of binary)
+    sample = content[:sample_size]
+    if b"\x00" in sample:
+        return True
+
+    # Try to decode as UTF-8
+    try:
+        sample.decode("utf-8")
+        return False
+    except UnicodeDecodeError:
+        pass
+
+    # Try common text encodings
+    for encoding in ["latin-1", "cp1252"]:
+        try:
+            decoded = sample.decode(encoding)
+            # Check for high ratio of control characters (likely binary)
+            control_chars = sum(1 for c in decoded if ord(c) < 32 and c not in "\n\r\t")
+            if control_chars / len(decoded) > 0.1:
+                return True
+            return False
+        except UnicodeDecodeError:
+            continue
+
+    return True
+
+
+def strip_bom(content: str | bytes) -> str | bytes:
+    """
+    Remove BOM (Byte Order Mark) from content.
+
+    Args:
+        content: String or bytes that may contain BOM
+
+    Returns:
+        Content with BOM removed
+
+    Example:
+        clean_content = strip_bom(file_content)
+    """
+    if isinstance(content, bytes):
+        # UTF-8 BOM
+        if content.startswith(b"\xef\xbb\xbf"):
+            return content[3:]
+        # UTF-16 BOMs
+        if content.startswith((b"\xff\xfe", b"\xfe\xff")):
+            return content[2:]
+        # UTF-32 BOMs
+        if content.startswith((b"\xff\xfe\x00\x00", b"\x00\x00\xfe\xff")):
+            return content[4:]
+        return content
+
+    # String version
+    if content.startswith("\ufeff"):
+        return content[1:]
+    return content

coding_client/utils/enum_helpers.py

@@ -0,0 +1,166 @@
+"""
+Enum helper utilities for safe value extraction.
+
+This module provides utilities to reduce cyclomatic complexity when
+extracting values from enums or enum-like objects across the codebase.
+"""
+
+from enum import Enum
+from typing import Any, TypeVar, cast
+
+T = TypeVar("T")
+
+
+def safe_get_enum_value(
+    obj: Any,
+    attr_name: str,
+    default: str = "unknown",
+) -> str:
+    """
+    Safely extract enum value from an object attribute.
+
+    Handles cases where:
+    - The attribute doesn't exist
+    - The attribute is an Enum (extracts .value)
+    - The attribute is already a string
+    - The attribute is None
+
+    Args:
+        obj: Object to extract attribute from
+        attr_name: Name of the attribute to extract
+        default: Default value if attribute not found or None
+
+    Returns:
+        String value of the attribute
+
+    Example:
+        # Instead of:
+        # getattr(insight, "severity", "info").value if hasattr(...) else str(...)
+
+        # Use:
+        safe_get_enum_value(insight, "severity", "info")
+    """
+    value = getattr(obj, attr_name, None)
+
+    if value is None:
+        return default
+
+    if isinstance(value, Enum):
+        return str(value.value)
+
+    if hasattr(value, "value"):
+        return str(value.value)
+
+    return str(value)
+
+
+def safe_get_nested_enum(
+    obj: Any,
+    *attr_path: str,
+    default: str = "unknown",
+) -> str:
+    """
+    Safely extract enum value from a nested attribute path.
+
+    Args:
+        obj: Root object to start from
+        *attr_path: Sequence of attribute names to traverse
+        default: Default value if path doesn't exist
+
+    Returns:
+        String value of the final attribute
+
+    Example:
+        # Instead of deeply nested getattr chains:
+        safe_get_nested_enum(result, "analysis", "severity", default="low")
+    """
+    current = obj
+
+    for attr in attr_path:
+        current = getattr(current, attr, None)
+        if current is None:
+            return default
+
+    if isinstance(current, Enum):
+        return str(current.value)
+
+    if hasattr(current, "value"):
+        return str(current.value)
+
+    return str(current)
+
+
+def enum_to_str(value: Enum | str | None, default: str = "unknown") -> str:
+    """
+    Convert an enum or string to string representation.
+
+    Args:
+        value: Enum instance, string, or None
+        default: Default value if None
+
+    Returns:
+        String representation
+    """
+    if value is None:
+        return default
+
+    if isinstance(value, Enum):
+        return str(value.value)
+
+    if hasattr(value, "value"):
+        return str(value.value)
+
+    return str(value)
+
+
+def safe_enum_name(value: Enum | str | None, default: str = "unknown") -> str:
+    """
+    Get the name of an enum (not its value).
+
+    Args:
+        value: Enum instance or string
+        default: Default if None
+
+    Returns:
+        Enum name as string
+    """
+    if value is None:
+        return default
+
+    if isinstance(value, Enum):
+        return value.name
+
+    if hasattr(value, "name"):
+        return str(value.name)
+
+    return str(value)
+
+
+def get_enum_or_default[T](
+    enum_class: type,
+    value: Any,
+    default: T | None = None,
+) -> Enum | T | None:
+    """
+    Safely get an enum member by value, with fallback.
+
+    Args:
+        enum_class: The enum class to look up
+        value: Value to look up in the enum
+        default: Default to return if not found
+
+    Returns:
+        Enum member or default
+
+    Example:
+        status = get_enum_or_default(StatusEnum, "active", StatusEnum.UNKNOWN)
+    """
+    if value is None:
+        return default
+
+    try:
+        if isinstance(value, enum_class):
+            return cast(Enum, value)
+        return cast(Enum, enum_class(value))
+    except (ValueError, KeyError):
+        return default

coding_client/utils/file_operations.py

@@ -0,0 +1,177 @@
+"""Common file operation utilities to reduce code duplication.
+
+This module provides reusable file handling functions for reading, writing,
+processing, and managing files across the application.
+
+This module now serves as a compatibility layer that imports from specialized modules:
+- filesystem_ops: Core file system operations
+- path_utils: Path validation and manipulation
+- content_processing: File content processing (JSON/YAML, encoding)
+- archive_utils: Backup, temp files, and atomic operations
+- security_validation: File security and validation
+"""
+
+from .archive_utils import (  # Archive and backup operations
+    async_atomic_write,
+    async_create_backup,
+    atomic_write,
+    cleanup_temp_files,
+    create_backup,
+    create_backup_directory,
+    create_temp_copy,
+    preserve_permissions,
+    safe_replace,
+    temp_directory,
+    temp_file,
+)
+from .content_processing import (  # Content processing
+    async_detect_encoding,
+    async_process_files,
+    async_read_json,
+    async_read_yaml,
+    async_write_json,
+    async_write_yaml,
+    detect_encoding,
+    format_json,
+    format_yaml,
+    process_files,
+    read_json,
+    read_yaml,
+    validate_json_content,
+    validate_yaml_content,
+    write_json,
+    write_yaml,
+)
+
+# Import all functions from specialized modules for backward compatibility
+from .filesystem_ops import (  # Exceptions; Core file operations
+    FileNotFoundError,
+    FileOperationError,
+    FilePermissionError,
+    FileSizeError,
+    append_to_file,
+    async_read_file,
+    async_read_file_chunks,
+    async_write_file,
+    copy_file,
+    delete_directory,
+    delete_file,
+    ensure_directory,
+    move_file,
+    read_file,
+    read_file_chunks,
+    read_file_lines,
+    write_file,
+)
+from .path_utils import (  # Path operations
+    create_directory_tree,
+    find_files_by_extension,
+    find_files_by_name,
+    find_files_containing,
+    get_directory_size,
+    get_relative_path,
+    is_empty_directory,
+    join_paths,
+    list_files,
+    normalize_path,
+    should_ignore_path,
+    validate_path,
+)
+from .security_validation import (  # Security and validation
+    check_file_integrity,
+    get_file_hash,
+    get_file_info,
+    get_file_permissions,
+    get_file_size,
+    get_safe_temp_dir,
+    is_executable_file,
+    is_safe_filename,
+    sanitize_filename,
+    validate_directory_access,
+    validate_file_access,
+    verify_file_hash,
+)
+
+# Export all public functions for backward compatibility
+__all__ = [
+    # Exceptions
+    "FileOperationError",
+    "FileSizeError",
+    "FileNotFoundError",
+    "FilePermissionError",
+    # Reading
+    "read_file",
+    "async_read_file",
+    "read_file_lines",
+    "read_file_chunks",
+    "async_read_file_chunks",
+    # Writing
+    "write_file",
+    "async_write_file",
+    "append_to_file",
+    # JSON
+    "read_json",
+    "async_read_json",
+    "write_json",
+    "async_write_json",
+    "validate_json_content",
+    "format_json",
+    # YAML
+    "read_yaml",
+    "async_read_yaml",
+    "write_yaml",
+    "async_write_yaml",
+    "validate_yaml_content",
+    "format_yaml",
+    # Directory operations
+    "ensure_directory",
+    "list_files",
+    "should_ignore_path",
+    "copy_file",
+    "move_file",
+    "delete_file",
+    "delete_directory",
+    # Path utilities
+    "normalize_path",
+    "validate_path",
+    "join_paths",
+    "get_relative_path",
+    "find_files_by_extension",
+    "find_files_by_name",
+    "find_files_containing",
+    "get_directory_size",
+    "is_empty_directory",
+    "create_directory_tree",
+    # Utilities
+    "get_file_size",
+    "get_file_hash",
+    "verify_file_hash",
+    "get_file_info",
+    "get_file_permissions",
+    "detect_encoding",
+    "async_detect_encoding",
+    # Security and validation
+    "validate_file_access",
+    "validate_directory_access",
+    "check_file_integrity",
+    "is_safe_filename",
+    "sanitize_filename",
+    "is_executable_file",
+    "get_safe_temp_dir",
+    # Archive and backup
+    "create_backup",
+    "async_create_backup",
+    "create_backup_directory",
+    "create_temp_copy",
+    "safe_replace",
+    "cleanup_temp_files",
+    # Context managers
+    "temp_file",
+    "temp_directory",
+    "atomic_write",
+    "async_atomic_write",
+    "preserve_permissions",
+    # Processing
+    "process_files",
+    "async_process_files",
+]