taipanstack 0.1.0__py3-none-any.whl

taipanstack/core/result.py

@@ -0,0 +1,199 @@
+"""
+Result type utilities for functional error handling.
+
+Provides Rust-style Result types (Ok/Err) for explicit error handling,
+avoiding exceptions for expected failure cases. This promotes safer,
+more predictable code.
+
+Example:
+    >>> from taipanstack.core.result import safe, Ok, Err
+    >>> @safe
+    ... def divide(a: int, b: int) -> float:
+    ...     if b == 0:
+    ...         raise ValueError("division by zero")
+    ...     return a / b
+    >>> result = divide(10, 0)
+    >>> match result:
+    ...     case Err(e):
+    ...         print(f"Error: {e}")
+    ...     case Ok(value):
+    ...         print(f"Result: {value}")
+    Error: division by zero
+
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable, Iterable
+from typing import ParamSpec, TypeVar
+
+from result import Err, Ok, Result
+
+__all__ = [
+    "Err",
+    "Ok",
+    "Result",
+    "collect_results",
+    "safe",
+    "safe_from",
+    "unwrap_or",
+    "unwrap_or_else",
+]
+
+P = ParamSpec("P")
+T = TypeVar("T")
+E = TypeVar("E", bound=Exception)
+U = TypeVar("U")
+
+
+def safe(
+    func: Callable[P, T],
+) -> Callable[P, Result[T, Exception]]:
+    """Decorator to convert exceptions into Err results.
+
+    Wraps a function so that any exception raised becomes an Err,
+    while successful returns become Ok.
+
+    Args:
+        func: The function to wrap.
+
+    Returns:
+        A wrapped function that returns Result[T, Exception].
+
+    Example:
+        >>> @safe
+        ... def parse_int(s: str) -> int:
+        ...     return int(s)
+        >>> parse_int("42")
+        Ok(42)
+        >>> parse_int("invalid")
+        Err(ValueError("invalid literal for int()..."))
+
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[T, Exception]:
+        try:
+            return Ok(func(*args, **kwargs))
+        except Exception as e:
+            return Err(e)
+
+    return wrapper
+
+
+def safe_from(
+    *exception_types: type[E],
+) -> Callable[[Callable[P, T]], Callable[P, Result[T, E]]]:
+    """Decorator factory to catch specific exceptions as Err.
+
+    Only catches specified exception types; others propagate normally.
+
+    Args:
+        *exception_types: Exception types to convert to Err.
+
+    Returns:
+        Decorator that wraps function with selective error handling.
+
+    Example:
+        >>> @safe_from(ValueError, TypeError)
+        ... def process(data: str) -> int:
+        ...     return int(data)
+        >>> process("abc")
+        Err(ValueError(...))
+
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, Result[T, E]]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[T, E]:
+            try:
+                return Ok(func(*args, **kwargs))
+            except exception_types as e:
+                return Err(e)
+
+        return wrapper
+
+    return decorator
+
+
+def collect_results(
+    results: Iterable[Result[T, E]],
+) -> Result[list[T], E]:
+    """Collect an iterable of Results into a single Result.
+
+    If all results are Ok, returns Ok with list of values.
+    If any result is Err, returns the first Err encountered.
+
+    Args:
+        results: Iterable of Result objects.
+
+    Returns:
+        Ok(list[T]) if all are Ok, otherwise first Err.
+
+    Example:
+        >>> collect_results([Ok(1), Ok(2), Ok(3)])
+        Ok([1, 2, 3])
+        >>> collect_results([Ok(1), Err("fail"), Ok(3)])
+        Err("fail")
+
+    """
+    values: list[T] = []
+    for result in results:
+        match result:
+            case Ok(value):
+                values.append(value)
+            case Err() as err:
+                return err
+    return Ok(values)
+
+
+def unwrap_or(result: Result[T, E], default: T) -> T:
+    """Extract value from Result or return default.
+
+    Args:
+        result: The Result to unwrap.
+        default: Default value if result is Err.
+
+    Returns:
+        The Ok value or the default.
+
+    Example:
+        >>> unwrap_or(Ok(42), 0)
+        42
+        >>> unwrap_or(Err("error"), 0)
+        0
+
+    """
+    match result:
+        case Ok(value):
+            return value
+        case Err():
+            return default
+
+
+def unwrap_or_else(
+    result: Result[T, E],
+    default_fn: Callable[[E], T],
+) -> T:
+    """Extract value from Result or compute default from error.
+
+    Args:
+        result: The Result to unwrap.
+        default_fn: Function to compute default from error.
+
+    Returns:
+        The Ok value or computed default.
+
+    Example:
+        >>> unwrap_or_else(Ok(42), lambda e: 0)
+        42
+        >>> unwrap_or_else(Err(ValueError("x")), lambda e: len(str(e)))
+        1
+
+    """
+    match result:
+        case Ok(value):
+            return value
+        case Err(error):
+            return default_fn(error)

taipanstack/security/__init__.py

@@ -0,0 +1,55 @@
+"""Security package for runtime protection."""
+
+from taipanstack.security.decorators import (
+    OperationTimeoutError,
+    ValidationError,
+    deprecated,
+    guard_exceptions,
+    require_type,
+    timeout,
+    validate_inputs,
+)
+from taipanstack.security.guards import (
+    SecurityError,
+    guard_command_injection,
+    guard_env_variable,
+    guard_file_extension,
+    guard_path_traversal,
+)
+from taipanstack.security.sanitizers import (
+    sanitize_filename,
+    sanitize_path,
+    sanitize_string,
+)
+from taipanstack.security.validators import (
+    validate_email,
+    validate_project_name,
+    validate_python_version,
+    validate_url,
+)
+
+__all__ = [
+    # Decorators
+    "OperationTimeoutError",
+    # Guards
+    "SecurityError",
+    "ValidationError",
+    "deprecated",
+    "guard_command_injection",
+    "guard_env_variable",
+    "guard_exceptions",
+    "guard_file_extension",
+    "guard_path_traversal",
+    "require_type",
+    # Sanitizers
+    "sanitize_filename",
+    "sanitize_path",
+    "sanitize_string",
+    "timeout",
+    # Validators
+    "validate_email",
+    "validate_inputs",
+    "validate_project_name",
+    "validate_python_version",
+    "validate_url",
+]

taipanstack/security/decorators.py

@@ -0,0 +1,369 @@
+"""
+Security decorators for robust Python applications.
+
+Provides decorators for input validation, exception handling,
+timeout control, and other security patterns. Compatible with
+any Python framework (Flask, FastAPI, Django, etc.).
+"""
+
+from __future__ import annotations
+
+import functools
+import signal
+import sys
+import threading
+from collections.abc import Callable, Mapping
+from typing import Any, ParamSpec, TypeVar
+
+from taipanstack.security.guards import SecurityError
+
+P = ParamSpec("P")
+R = TypeVar("R")
+T = TypeVar("T")
+
+
+class OperationTimeoutError(Exception):
+    """Raised when a function exceeds its timeout limit."""
+
+    def __init__(self, seconds: float, func_name: str = "function") -> None:
+        """Initialize OperationTimeoutError.
+
+        Args:
+            seconds: The timeout that was exceeded.
+            func_name: Name of the function that timed out.
+
+        """
+        self.seconds = seconds
+        self.func_name = func_name
+        super().__init__(f"{func_name} timed out after {seconds} seconds")
+
+
+class ValidationError(Exception):
+    """Raised when input validation fails."""
+
+    def __init__(
+        self,
+        message: str,
+        param_name: str | None = None,
+        value: Any = None,
+    ) -> None:
+        """Initialize ValidationError.
+
+        Args:
+            message: Description of the validation failure.
+            param_name: Name of the parameter that failed.
+            value: The invalid value (sanitized).
+
+        """
+        self.param_name = param_name
+        self.value = value
+        super().__init__(message)
+
+
+def validate_inputs(
+    **validators: Callable[[Any], Any],
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator to validate function inputs.
+
+    Validates function arguments using provided validator functions.
+    Validators should raise ValueError or ValidationError on invalid input.
+
+    Args:
+        **validators: Mapping of parameter names to validator functions.
+
+    Returns:
+        Decorated function with input validation.
+
+    Example:
+        >>> from taipanstack.security.validators import validate_email, validate_port
+        >>> @validate_inputs(email=validate_email, port=validate_port)
+        ... def connect(email: str, port: int) -> None:
+        ...     pass
+        >>> connect(email="invalid", port=8080)
+        ValidationError: Invalid email format: invalid
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # Get function's parameter names
+            import inspect
+
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            # Validate each parameter that has a validator
+            for param_name, validator in validators.items():
+                if param_name in bound.arguments:
+                    value = bound.arguments[param_name]
+                    try:
+                        # Call validator - it should raise on invalid input
+                        validated = validator(value)
+                        # Update to validated value if returned
+                        if validated is not None:
+                            bound.arguments[param_name] = validated
+                    except (ValueError, TypeError) as e:
+                        raise ValidationError(
+                            str(e),
+                            param_name=param_name,
+                            value=repr(value)[:100],
+                        ) from e
+
+            # Call original function with validated arguments
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def guard_exceptions(
+    *,
+    catch: tuple[type[Exception], ...] = (Exception,),
+    reraise_as: type[Exception] | None = None,
+    default: Any = None,
+    log_errors: bool = True,
+) -> Callable[[Callable[P, R]], Callable[P, R | Any]]:
+    """Decorator to safely handle exceptions.
+
+    Catches exceptions and optionally re-raises as a different type
+    or returns a default value.
+
+    Args:
+        catch: Exception types to catch.
+        reraise_as: Exception type to re-raise as (None = don't reraise).
+        default: Default value to return if exception caught and not reraised.
+        log_errors: Whether to log caught exceptions.
+
+    Returns:
+        Decorated function with exception handling.
+
+    Example:
+        >>> @guard_exceptions(catch=(IOError,), reraise_as=SecurityError)
+        ... def read_file(path: str) -> str:
+        ...     return open(path).read()
+        >>> read_file("/nonexistent")
+        SecurityError: [guard_exceptions] ...
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R | Any]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | Any:
+            try:
+                return func(*args, **kwargs)
+            except catch as e:
+                if log_errors:
+                    import logging
+
+                    logging.getLogger("taipanstack.security").warning(
+                        "Exception caught in %s: %s",
+                        func.__name__,
+                        str(e),
+                    )
+
+                if reraise_as is not None:
+                    if reraise_as == SecurityError:
+                        raise SecurityError(
+                            str(e),
+                            guard_name="guard_exceptions",
+                        ) from e
+                    raise reraise_as(str(e)) from e
+
+                return default
+
+        return wrapper
+
+    return decorator
+
+
+def timeout(
+    seconds: float,
+    *,
+    use_signal: bool = True,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator to limit function execution time.
+
+    Uses signal-based timeout on Unix or thread-based on Windows.
+    Signal-based is more reliable but only works in main thread.
+
+    Args:
+        seconds: Maximum execution time in seconds.
+        use_signal: Use signal-based timeout (Unix only, main thread only).
+
+    Returns:
+        Decorated function with timeout.
+
+    Example:
+        >>> @timeout(5.0)
+        ... def slow_operation() -> str:
+        ...     import time
+        ...     time.sleep(10)
+        ...     return "done"
+        >>> slow_operation()
+        TimeoutError: slow_operation timed out after 5.0 seconds
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # Determine if we can use signals
+            can_use_signal = (
+                use_signal
+                and sys.platform != "win32"
+                and threading.current_thread() is threading.main_thread()
+            )
+
+            if can_use_signal:
+                return _timeout_with_signal(func, seconds, args, kwargs)
+            return _timeout_with_thread(func, seconds, args, kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def _timeout_with_signal(
+    func: Callable[P, R],
+    seconds: float,
+    args: tuple[Any, ...],
+    kwargs: Mapping[str, Any],
+) -> R:
+    """Implement timeout using Unix signals."""
+
+    def handler(signum: int, frame: Any) -> None:
+        raise OperationTimeoutError(seconds, func.__name__)
+
+    # Set up signal handler
+    old_handler = signal.signal(signal.SIGALRM, handler)
+    signal.setitimer(signal.ITIMER_REAL, seconds)
+
+    try:
+        return func(*args, **kwargs)
+    finally:
+        # Restore old handler and cancel alarm
+        signal.setitimer(signal.ITIMER_REAL, 0)
+        signal.signal(signal.SIGALRM, old_handler)
+
+
+def _timeout_with_thread(
+    func: Callable[P, R],
+    seconds: float,
+    args: tuple[Any, ...],
+    kwargs: Mapping[str, Any],
+) -> R:
+    """Implement timeout using a separate thread."""
+    result: list[R] = []
+    exception: list[Exception] = []
+
+    def target() -> None:
+        try:
+            result.append(func(*args, **kwargs))
+        except Exception as e:
+            exception.append(e)
+
+    thread = threading.Thread(target=target)
+    thread.daemon = True
+    thread.start()
+    thread.join(timeout=seconds)
+
+    if thread.is_alive():
+        # Thread still running - timeout occurred
+        raise OperationTimeoutError(seconds, func.__name__)
+
+    if exception:
+        raise exception[0]
+
+    return result[0]
+
+
+def deprecated(
+    message: str = "",
+    *,
+    removal_version: str | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Mark a function as deprecated.
+
+    Emits a warning when the decorated function is called.
+
+    Args:
+        message: Additional deprecation message.
+        removal_version: Version when function will be removed.
+
+    Returns:
+        Decorated function that warns on use.
+
+    Example:
+        >>> @deprecated("Use new_function instead", removal_version="2.0")
+        ... def old_function() -> None:
+        ...     pass
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            import warnings
+
+            msg = f"{func.__name__} is deprecated."
+            if removal_version:
+                msg += f" Will be removed in version {removal_version}."
+            if message:
+                msg += f" {message}"
+
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def require_type(
+    **type_hints: type,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator to enforce runtime type checking.
+
+    Validates that arguments match specified types at runtime.
+
+    Args:
+        **type_hints: Mapping of parameter names to expected types.
+
+    Returns:
+        Decorated function with type checking.
+
+    Example:
+        >>> @require_type(name=str, count=int)
+        ... def greet(name: str, count: int) -> None:
+        ...     print(f"Hello {name}" * count)
+        >>> greet(name=123, count=2)
+        TypeError: Parameter 'name' expected str, got int
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            import inspect
+
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            for param_name, expected_type in type_hints.items():
+                if param_name in bound.arguments:
+                    value = bound.arguments[param_name]
+                    if not isinstance(value, expected_type):
+                        raise TypeError(
+                            f"Parameter '{param_name}' expected "
+                            f"{expected_type.__name__}, got {type(value).__name__}"
+                        )
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
+
+    return decorator