ostruct-cli 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

ostruct/cli/errors.py

@@ -1,47 +1,14 @@
 """Custom error classes for CLI error handling."""
 
-import os
-from pathlib import Path
-from typing import Any, Dict, List, Optional, TextIO, cast
+import logging
+from typing import Any, Dict, List, Optional
 
-import click
+from .base_errors import CLIError, OstructFileNotFoundError
+from .exit_codes import ExitCode
+from .security.base import SecurityErrorBase
+from .security.errors import SecurityErrorReasons
 
-
-class CLIError(click.ClickException):
-    """Base class for all CLI errors."""
-
-    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None):
-        super().__init__(message)
-        self.context = context or {}
-        self._has_been_logged = False  # Use underscore for private attribute
-
-    @property
-    def has_been_logged(self) -> bool:
-        """Whether this error has been logged."""
-        return self._has_been_logged
-
-    @has_been_logged.setter
-    def has_been_logged(self, value: bool) -> None:
-        """Set whether this error has been logged."""
-        self._has_been_logged = value
-
-    def show(self, file: Optional[TextIO] = None) -> None:
-        """Show the error message with optional context."""
-        if file is None:
-            file = cast(TextIO, click.get_text_stream("stderr"))
-
-        # Format message with context if available
-        if self.context:
-            context_str = "\n".join(
-                f"  {k}: {v}" for k, v in self.context.items()
-            )
-            click.secho(
-                f"Error: {self.message}\nContext:\n{context_str}",
-                fg="red",
-                file=file,
-            )
-        else:
-            click.secho(f"Error: {self.message}", fg="red", file=file)
+logger = logging.getLogger(__name__)
 
 
 class VariableError(CLIError):
@@ -63,7 +30,7 @@ class VariableValueError(VariableError):
 
 
 class InvalidJSONError(CLIError):
-    """Raised when JSON parsing fails for a variable value."""
+    """Error raised when JSON is invalid."""
 
     def __init__(
         self,
@@ -71,236 +38,191 @@ class InvalidJSONError(CLIError):
         source: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
     ):
+        """Initialize invalid JSON error.
+
+        Args:
+            message: Error message
+            source: Source of invalid JSON
+            context: Additional context for the error
+        """
         context = context or {}
         if source:
             context["source"] = source
-        super().__init__(message, context)
+        super().__init__(
+            message,
+            exit_code=ExitCode.DATA_ERROR,
+            context=context,
+        )
 
 
 class PathError(CLIError):
     """Base class for path-related errors."""
 
     def __init__(
-        self, message: str, path: str, context: Optional[Dict[str, Any]] = None
+        self,
+        message: str,
+        path: str,
+        context: Optional[Dict[str, Any]] = None,
+        exit_code: int = ExitCode.FILE_ERROR,
     ):
         context = context or {}
         context["path"] = path
-        super().__init__(message, context)
+        super().__init__(message, context=context, exit_code=exit_code)
 
 
-class FileNotFoundError(PathError):
-    """Raised when a specified file does not exist."""
+class FileReadError(PathError):
+    """Raised when a file cannot be read or decoded.
 
-    def __init__(self, path: str, context: Optional[Dict[str, Any]] = None):
-        # Use path directly as the message without prepending "File not found: "
-        super().__init__(path, path, context)
+    This is a wrapper exception that preserves the original cause (FileNotFoundError,
+    UnicodeDecodeError, etc) while providing a consistent interface for error handling.
+    """
+
+    def __init__(
+        self, message: str, path: str, context: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, path, context)
 
 
 class DirectoryNotFoundError(PathError):
     """Raised when a specified directory does not exist."""
 
     def __init__(self, path: str, context: Optional[Dict[str, Any]] = None):
-        # Use path directly as the message without prepending "Directory not found: "
-        super().__init__(path, path, context)
-
+        context = context or {}
+        context.update(
+            {
+                "details": "The specified directory does not exist or cannot be accessed",
+                "troubleshooting": [
+                    "Check if the directory exists",
+                    "Verify the path spelling is correct",
+                    "Check directory permissions",
+                    "Ensure parent directories exist",
+                    "Use --allowed-dir to specify additional allowed directories",
+                ],
+            }
+        )
+        super().__init__(
+            f"Directory not found: {path}", path=path, context=context
+        )
 
-class PathSecurityError(PathError):
-    """Exception raised when file access is denied due to security constraints.
 
-    Attributes:
-        message: The error message with full context
-        wrapped: Whether this error has been wrapped by another error
-    """
+class PathSecurityError(SecurityErrorBase):
+    """Error raised when a path violates security constraints."""
 
     def __init__(
         self,
         message: str,
         path: Optional[str] = None,
-        context: Optional[Dict[str, Any]] = None,
         error_logged: bool = False,
-    ):
-        path = path or "unknown"  # Provide default path if none given
+        wrapped: bool = False,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize error.
+
+        Args:
+            message: Error message
+            path: Path that caused the error
+            error_logged: Whether error has been logged
+            wrapped: Whether this is a wrapped error
+            context: Additional error context
+        """
         context = context or {}
-        context["has_been_logged"] = (
-            error_logged  # Store in context to match parent behavior
-        )
-        context["wrapped"] = False  # Initialize wrapped state
-        super().__init__(message, path, context)
-
-    def __str__(self) -> str:
-        """Return string representation with allowed directories if present."""
-        base = super().__str__()
-        if self.context and "allowed_dirs" in self.context:
-            allowed = self.context["allowed_dirs"]
-            if allowed:  # Only add if there are actually allowed dirs
-                return f"{base} (allowed directories: {', '.join(allowed)})"
-        return base
-
-    @property
-    def has_been_logged(self) -> bool:
-        """Whether this error has been logged."""
-        return bool(self.context.get("has_been_logged", False))
+        if path is not None:
+            context["path"] = path
+            context.setdefault(
+                "details", "The specified path violates security constraints"
+            )
+            context.setdefault(
+                "troubleshooting",
+                [
+                    "Check if the path is within allowed directories",
+                    "Use --allowed-dir to specify additional allowed directories",
+                    "Verify path permissions",
+                ],
+            )
 
-    @has_been_logged.setter
-    def has_been_logged(self, value: bool) -> None:
-        """Set whether this error has been logged."""
-        self.context["has_been_logged"] = value
+        super().__init__(message, context=context)
+        self._wrapped = wrapped
+        self._error_logged = error_logged
 
     @property
     def error_logged(self) -> bool:
-        """Alias for has_been_logged for backward compatibility."""
-        return self.has_been_logged
-
-    @error_logged.setter
-    def error_logged(self, value: bool) -> None:
-        """Alias for has_been_logged for backward compatibility."""
-        self.has_been_logged = value
+        """Whether this error has been logged."""
+        return self._error_logged
 
     @property
     def wrapped(self) -> bool:
-        """Whether this error has been wrapped by another error."""
-        return bool(self.context.get("wrapped", False))
-
-    @wrapped.setter
-    def wrapped(self, value: bool) -> None:
-        """Set whether this error has been wrapped."""
-        self.context["wrapped"] = value
-
-    @staticmethod
-    def _format_allowed_dirs(allowed_dirs: List[str]) -> str:
-        """Format allowed directories as a list representation."""
-        return f"[{', '.join(repr(d) for d in allowed_dirs)}]"
-
-    @staticmethod
-    def _create_error_message(
-        path: str, base_dir: Optional[str] = None
-    ) -> str:
-        """Create a standardized error message."""
-        if base_dir:
-            rel_path = os.path.relpath(path, base_dir)
-            return f"Access denied: {rel_path} is outside base directory and not in allowed directories"
-        return f"Access denied: {path} is outside base directory and not in allowed directories"
+        """Whether this is a wrapped error."""
+        return self._wrapped
 
     @classmethod
     def from_expanded_paths(
         cls,
         original_path: str,
         expanded_path: str,
-        base_dir: Optional[str] = None,
-        allowed_dirs: Optional[List[str]] = None,
+        base_dir: str,
+        allowed_dirs: List[str],
         error_logged: bool = False,
     ) -> "PathSecurityError":
-        """Create error with expanded path context."""
-        message = f"Access denied: {original_path} is outside base directory and not in allowed directories"
-        if expanded_path != original_path:
-            message += f" (expanded to {expanded_path})"
-
+        """Create error with expanded path information.
+
+        Args:
+            original_path: Original path provided
+            expanded_path: Expanded absolute path
+            base_dir: Base directory
+            allowed_dirs: List of allowed directories
+            error_logged: Whether error has been logged
+
+        Returns:
+            PathSecurityError instance
+        """
         context = {
             "original_path": original_path,
             "expanded_path": expanded_path,
-            "has_been_logged": error_logged,
+            "base_dir": base_dir,
+            "allowed_dirs": allowed_dirs,
+            "reason": SecurityErrorReasons.PATH_OUTSIDE_ALLOWED,
+            "details": "The path resolves to a location outside the allowed directories",
+            "troubleshooting": [
+                f"Ensure path is within base directory: {base_dir}",
+                "Use --allowed-dir to specify additional allowed directories",
+                f"Current allowed directories: {', '.join(allowed_dirs)}",
+            ],
         }
-        if base_dir:
-            context["base_dir"] = base_dir
-        if allowed_dirs:
-            context["allowed_dirs"] = allowed_dirs
-
-        # Format full message with all context
-        parts = [message]
-        if base_dir:
-            parts.append(f"Base directory: {base_dir}")
-        if allowed_dirs:
-            parts.append(
-                f"Allowed directories: {cls._format_allowed_dirs(allowed_dirs)}"
-            )
-        parts.append(
-            "Use --allowed-dir to specify additional allowed directories"
-        )
 
         return cls(
-            "\n".join(parts),
+            f"Access denied: {original_path!r} resolves to {expanded_path!r} which is "
+            f"outside base directory {base_dir!r}",
             path=original_path,
-            context=context,
             error_logged=error_logged,
+            context=context,
         )
 
     @classmethod
-    def access_denied(
-        cls,
-        path: Path,
-        reason: Optional[str] = None,
-        error_logged: bool = False,
-    ) -> "PathSecurityError":
-        """Create access denied error."""
-        msg = f"Access denied: {path}"
-        if reason:
-            msg += f" - {reason}"
-        msg += " is outside base directory and not in allowed directories"
-        return cls(msg, path=str(path), error_logged=error_logged)
+    def wrap_error(cls, msg: str, original: Exception) -> "PathSecurityError":
+        """Wrap an existing error with additional context.
 
-    @classmethod
-    def outside_allowed(
-        cls,
-        path: Path,
-        base_dir: Optional[Path] = None,
-        error_logged: bool = False,
-    ) -> "PathSecurityError":
-        """Create error for path outside allowed directories."""
-        msg = f"Access denied: {path} is outside base directory and not in allowed directories"
-        context = {}
-        if base_dir:
-            context["base_directory"] = str(base_dir)
-        return cls(
-            msg, path=str(path), context=context, error_logged=error_logged
-        )
+        Args:
+            msg: New error message
+            original: Original error to wrap
 
-    @classmethod
-    def traversal_attempt(
-        cls, path: Path, error_logged: bool = False
-    ) -> "PathSecurityError":
-        """Create error for directory traversal attempt."""
-        msg = f"Access denied: {path} - directory traversal not allowed"
-        return cls(msg, path=str(path), error_logged=error_logged)
+        Returns:
+            New PathSecurityError instance
+        """
+        context = {
+            "wrapped_error": type(original).__name__,
+            "original_message": str(original),
+        }
 
-    def format_with_context(
-        self,
-        original_path: Optional[str] = None,
-        expanded_path: Optional[str] = None,
-        base_dir: Optional[str] = None,
-        allowed_dirs: Optional[List[str]] = None,
-    ) -> str:
-        """Format error message with additional context."""
-        parts = [self.message]
-        if original_path and expanded_path and original_path != expanded_path:
-            parts.append(f"Original path: {original_path}")
-            parts.append(f"Expanded path: {expanded_path}")
-        if base_dir:
-            parts.append(f"Base directory: {base_dir}")
-        if allowed_dirs:
-            parts.append(
-                f"Allowed directories: {self._format_allowed_dirs(allowed_dirs)}"
-            )
-        parts.append(
-            "Use --allowed-dir to specify additional allowed directories"
-        )
-        return "\n".join(parts)
+        if hasattr(original, "context"):
+            context.update(original.context)
 
-    @classmethod
-    def wrap_error(
-        cls, context: str, original: "PathSecurityError"
-    ) -> "PathSecurityError":
-        """Wrap an error with additional context while preserving attributes."""
-        message = f"{context}: {original.message}"
-        new_context = original.context.copy()
-        new_context["wrapped"] = True  # Mark as wrapped
-        error = cls(
-            message,
-            path=original.context.get("path", "unknown"),
-            context=new_context,
-            error_logged=original.has_been_logged,
+        return cls(
+            f"{msg}: {str(original)}",
+            path=getattr(original, "path", None),
+            error_logged=getattr(original, "error_logged", False),
+            wrapped=True,
+            context=context,
         )
-        error.wrapped = True  # Ensure wrapped is set through the property
-        return error
 
 
 class TaskTemplateError(CLIError):
@@ -318,7 +240,22 @@ class TaskTemplateSyntaxError(TaskTemplateError):
 class TaskTemplateVariableError(TaskTemplateError):
     """Raised when a task template uses undefined variables."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+        """
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.VALIDATION_ERROR,
+        )
 
 
 class TemplateValidationError(TaskTemplateError):
@@ -340,18 +277,49 @@ class SchemaError(CLIError):
 
 
 class SchemaFileError(CLIError):
-    """Raised when a schema file is invalid or inaccessible."""
+    """Error raised when schema file cannot be read."""
 
     def __init__(
         self,
         message: str,
         schema_path: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
-    ):
+    ) -> None:
+        """Initialize schema file error.
+
+        Args:
+            message: Error message
+            schema_path: Path to schema file
+            context: Additional context for the error
+        """
         context = context or {}
-        if schema_path:
+        if schema_path and "source" not in context:
             context["schema_path"] = schema_path
-        super().__init__(message, context)
+            context["source"] = schema_path  # Use new standard field
+            context.setdefault(
+                "details",
+                "The schema file could not be read or contains errors",
+            )
+            context.setdefault(
+                "troubleshooting",
+                [
+                    "Verify the schema file exists",
+                    "Check if the schema file contains valid JSON",
+                    "Ensure the schema follows the correct format",
+                    "Check file permissions",
+                ],
+            )
+
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.SCHEMA_ERROR,
+        )
+
+    @property
+    def schema_path(self) -> Optional[str]:
+        """Get the schema path."""
+        return self.context.get("schema_path")
 
 
 class SchemaValidationError(CLIError):
@@ -366,7 +334,23 @@ class SchemaValidationError(CLIError):
         context = context or {}
         if schema_path:
             context["schema_path"] = schema_path
-        super().__init__(message, context)
+            context["source"] = schema_path
+            context.setdefault("details", "The schema validation failed")
+            context.setdefault(
+                "troubleshooting",
+                [
+                    "Check if the schema follows JSON Schema specification",
+                    "Verify all required fields are present",
+                    "Ensure field types are correctly specified",
+                    "Check for any syntax errors in the schema",
+                ],
+            )
+
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.SCHEMA_ERROR,
+        )
 
 
 class ModelCreationError(CLIError):
@@ -415,12 +399,6 @@ class ModelNotSupportedError(CLIError):
     pass
 
 
-class ModelVersionError(CLIError):
-    """Exception raised when a model version is not supported."""
-
-    pass
-
-
 class StreamInterruptedError(CLIError):
     """Exception raised when a stream is interrupted."""
 
@@ -458,25 +436,34 @@ class InvalidResponseFormatError(CLIError):
 
 
 class OpenAIClientError(CLIError):
-    """Exception raised when there's an error with the OpenAI client."""
+    """Exception raised when there's an error with the OpenAI client.
 
-    pass
+    This is a wrapper around openai_structured's OpenAIClientError to maintain
+    compatibility with our CLI error handling.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
 
 
 # Export public API
 __all__ = [
-    "CLIError",
     "VariableError",
     "PathError",
     "PathSecurityError",
-    "FileNotFoundError",
+    "OstructFileNotFoundError",
+    "FileReadError",
     "DirectoryNotFoundError",
     "SchemaValidationError",
     "SchemaFileError",
     "InvalidJSONError",
     "ModelCreationError",
     "ModelNotSupportedError",
-    "ModelVersionError",
     "StreamInterruptedError",
     "StreamBufferError",
     "StreamParseError",

ostruct/cli/exit_codes.py

@@ -0,0 +1,18 @@
+"""Exit codes for CLI operations."""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Exit codes for CLI operations."""
+
+    SUCCESS = 0
+    INTERNAL_ERROR = 1
+    USAGE_ERROR = 2
+    DATA_ERROR = 3
+    VALIDATION_ERROR = 4
+    API_ERROR = 5
+    SCHEMA_ERROR = 6
+    UNKNOWN_ERROR = 7
+    SECURITY_ERROR = 8
+    FILE_ERROR = 9