realitydefender 0.1.0__py3-none-any.whl

realitydefender/__init__.py

@@ -0,0 +1,370 @@
+"""
+Reality Defender SDK
+Client library for deepfake detection using the Reality Defender API
+"""
+
+import asyncio
+import os
+from typing import Any, Callable, Optional, cast
+
+from .client import create_http_client
+from .core.constants import DEFAULT_POLLING_INTERVAL, DEFAULT_TIMEOUT
+from .core.events import EventEmitter
+from .detection.results import get_detection_result
+from .detection.upload import upload_file
+from .errors import ErrorCode, RealityDefenderError
+from .types import (
+    DetectionOptions,
+    DetectionResult,
+    GetResultOptions,
+    RealityDefenderConfig,
+    UploadOptions,
+    UploadResult,
+)
+
+__all__ = [
+    "RealityDefender",
+    "upload_file",
+    "get_detection_result",
+    "RealityDefenderError",
+    "ErrorCode",
+    "RealityDefenderConfig",
+    "UploadOptions",
+    "UploadResult",
+    "DetectionResult",
+    "GetResultOptions",
+    "DetectionOptions",
+]
+
+
+class RealityDefender(EventEmitter):
+    """
+    Main SDK class for interacting with the Reality Defender API
+    """
+
+    def __init__(self, config: RealityDefenderConfig):
+        """
+        Creates a new Reality Defender SDK instance
+
+        Args:
+            config: Configuration options including API key
+
+        Raises:
+            RealityDefenderError: If API key is missing
+        """
+        super().__init__()
+
+        if not config.get("api_key"):
+            raise RealityDefenderError("API key is required", "unauthorized")
+
+        self.api_key = config["api_key"]
+        self.client = create_http_client(
+            {"api_key": self.api_key, "base_url": config.get("base_url")}
+        )
+
+    async def upload(self, options: UploadOptions) -> UploadResult:
+        """
+        Upload a file to Reality Defender for analysis (async version)
+
+        Args:
+            options: Upload options including file path
+
+        Returns:
+            Dictionary with request_id and media_id
+
+        Raises:
+            RealityDefenderError: If upload fails
+        """
+        try:
+            result = await upload_file(self.client, options)
+            return result
+        except RealityDefenderError:
+            raise
+        except Exception as error:
+            raise RealityDefenderError(f"Upload failed: {str(error)}", "upload_failed")
+
+    def upload_sync(self, options: UploadOptions) -> UploadResult:
+        """
+        Upload a file to Reality Defender for analysis (synchronous version)
+
+        This is a convenience wrapper around the async upload method.
+
+        Args:
+            options: Upload options including file path
+
+        Returns:
+            Dictionary with request_id and media_id
+
+        Raises:
+            RealityDefenderError: If upload fails
+        """
+        return self._run_async(self.upload(options))
+
+    def upload_file(self, file_path: str) -> UploadResult:
+        """
+        Upload a file to Reality Defender for analysis (simplified version)
+
+        This is a more Pythonic convenience method that takes a direct file path.
+
+        Args:
+            file_path: Path to the file to analyze
+
+        Returns:
+            Dictionary with request_id and media_id
+
+        Raises:
+            RealityDefenderError: If upload fails
+        """
+        if not os.path.exists(file_path):
+            raise RealityDefenderError(f"File not found: {file_path}", "invalid_file")
+
+        return self.upload_sync({"file_path": file_path})
+
+    async def get_result(
+        self, request_id: str, options: Optional[GetResultOptions] = None
+    ) -> DetectionResult:
+        """
+        Get the detection result for a specific request ID (async version)
+
+        Args:
+            request_id: The request ID to get results for
+            options: Optional parameters for polling
+
+        Returns:
+            Detection result with status and scores
+        """
+        if options is None:
+            options = {}
+        return await get_detection_result(self.client, request_id, options)
+
+    def get_result_sync(
+        self, request_id: str, options: Optional[GetResultOptions] = None
+    ) -> DetectionResult:
+        """
+        Get the detection result for a specific request ID (synchronous version)
+
+        This is a convenience wrapper around the async get_result method.
+
+        Args:
+            request_id: The request ID to get results for
+            options: Optional parameters for polling
+
+        Returns:
+            Detection result with status and scores
+        """
+        return self._run_async(self.get_result(request_id, options))
+
+    def detect_file(self, file_path: str) -> DetectionResult:
+        """
+        Convenience method to upload and detect a file in one step
+
+        This is a fully synchronous method that handles all async operations internally.
+
+        Args:
+            file_path: Path to the file to analyze
+
+        Returns:
+            Detection result with status and scores
+
+        Raises:
+            RealityDefenderError: If upload or detection fails
+        """
+        # Validation - more Pythonic to check path early
+        if not os.path.exists(file_path):
+            raise RealityDefenderError(f"File not found: {file_path}", "invalid_file")
+
+        # Upload the file
+        upload_result = self.upload_sync({"file_path": file_path})
+        request_id = upload_result["request_id"]
+
+        # Get the result
+        return self.get_result_sync(request_id)
+
+    def poll_for_results(
+        self,
+        request_id: str,
+        polling_interval: Optional[int] = None,
+        timeout: Optional[int] = None,
+    ) -> asyncio.Task:
+        """
+        Start polling for results with event-based callback (async version)
+
+        Args:
+            request_id: The request ID to poll for
+            polling_interval: Interval in milliseconds between polls (default: 2000)
+            timeout: Maximum time to poll in milliseconds (default: 60000)
+
+        Returns:
+            Asyncio task that can be awaited
+        """
+        polling_interval = polling_interval or DEFAULT_POLLING_INTERVAL
+        timeout = timeout or DEFAULT_TIMEOUT
+
+        return asyncio.create_task(
+            self._poll_for_results(request_id, polling_interval, timeout)
+        )
+
+    def poll_for_results_sync(
+        self,
+        request_id: str,
+        *,  # Force keyword arguments for better readability
+        polling_interval: Optional[int] = None,
+        timeout: Optional[int] = None,
+        on_result: Optional[Callable[[DetectionResult], None]] = None,
+        on_error: Optional[Callable[[RealityDefenderError], None]] = None,
+    ) -> None:
+        """
+        Start polling for results with synchronous callbacks
+
+        This is a convenience wrapper around the async poll_for_results method.
+
+        Args:
+            request_id: The request ID to poll for
+            polling_interval: Interval in milliseconds between polls (default: 2000)
+            timeout: Maximum time to poll in milliseconds (default: 60000)
+            on_result: Callback function when result is received
+            on_error: Callback function when error occurs
+        """
+        # Add event handlers if provided
+        if on_result:
+            # Cast to ResultHandler to satisfy type checker
+            from .types.events import ResultHandler
+            self.on("result", cast(ResultHandler, on_result))
+        if on_error:
+            # Cast to ErrorHandler to satisfy type checker
+            from .types.events import ErrorHandler
+            self.on("error", cast(ErrorHandler, on_error))
+
+        # Create and run the polling task
+        polling_task = self.poll_for_results(request_id, polling_interval, timeout)
+        self._run_async(polling_task)  # Return value not used in this case
+
+    async def _poll_for_results(
+        self, request_id: str, polling_interval: int, timeout: int
+    ) -> None:
+        """
+        Internal implementation of polling for results
+
+        Args:
+            request_id: The request ID to poll for
+            polling_interval: Interval in milliseconds between polls
+            timeout: Maximum time to poll in milliseconds
+        """
+        elapsed = 0
+        max_wait_time = timeout
+        is_completed = False
+
+        # Check if timeout is already zero/expired before starting
+        if timeout <= 0:
+            self.emit(
+                "error", RealityDefenderError("Polling timeout exceeded", "timeout")
+            )
+            return
+
+        while not is_completed and elapsed < max_wait_time:
+            try:
+                result = await self.get_result(request_id)
+
+                if result["status"] == "ANALYZING":
+                    elapsed += polling_interval
+                    await asyncio.sleep(polling_interval / 1000)  # Convert to seconds
+                else:
+                    # We have a final result
+                    is_completed = True
+                    self.emit("result", result)
+            except RealityDefenderError as error:
+                if error.code == "not_found":
+                    # Result not ready yet, continue polling
+                    elapsed += polling_interval
+                    await asyncio.sleep(polling_interval / 1000)  # Convert to seconds
+                else:
+                    # Any other error is emitted and polling stops
+                    is_completed = True
+                    self.emit("error", error)
+            except Exception as error:
+                is_completed = True
+                self.emit("error", RealityDefenderError(str(error), "unknown_error"))
+
+        # Check if we timed out
+        if not is_completed and elapsed >= max_wait_time:
+            self.emit(
+                "error", RealityDefenderError("Polling timeout exceeded", "timeout")
+            )
+
+    def _run_async(self, coro: Any) -> Any:
+        """
+        Run an async coroutine in a new event loop
+
+        Args:
+            coro: Coroutine to run
+
+        Returns:
+            The result of the coroutine
+
+        Raises:
+            RealityDefenderError: If the async operation fails
+        """
+        try:
+            # Get the current event loop, or create a new one if needed
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_closed():
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+            except RuntimeError:
+                # If there's no event loop in this thread, create one
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+
+            if loop.is_running():
+                # If the loop is already running, use run_coroutine_threadsafe
+                # This will likely happen in a GUI application or web server
+                future = asyncio.run_coroutine_threadsafe(coro, loop)
+                return future.result()
+            else:
+                # If not running, we can use the loop directly
+                return loop.run_until_complete(coro)
+        except Exception as e:
+            # Convert any asyncio errors to our own error format
+            if isinstance(e, RealityDefenderError):
+                raise e
+            raise RealityDefenderError(
+                f"Async operation failed: {str(e)}", "unknown_error"
+            )
+
+    async def cleanup(self) -> None:
+        """
+        Clean up resources used by the SDK
+
+        This should be called when you're done using the SDK to ensure all resources
+        are properly released.
+        """
+        if hasattr(self, "client") and self.client:
+            await self.client.close()
+
+    def cleanup_sync(self) -> None:
+        """
+        Synchronous version of cleanup
+
+        This should be called when you're done using the SDK to ensure all resources
+        are properly released.
+        """
+        self._run_async(self.cleanup())  # Discard the return value
+
+    def __del__(self) -> None:
+        """
+        Destructor to ensure resources are cleaned up
+
+        This will attempt to close any open sessions when the object is garbage collected.
+        It's still recommended to explicitly call cleanup() or cleanup_sync() when done.
+        """
+        try:
+            if hasattr(self, "client") and self.client:
+                # We can't use asyncio directly in __del__, so we'll try our best
+                # to clean up without relying on async operations
+                if hasattr(self.client, "session") and self.client.session:
+                    # Mark session for closing on GC - it's not perfect but better than nothing
+                    self.client.session._closed = True
+        except Exception:
+            # Suppress any errors during cleanup
+            pass

realitydefender/__version__.py

@@ -0,0 +1,5 @@
+"""
+Version information for the Reality Defender SDK
+"""
+
+__version__ = "0.1.0"

realitydefender/client/__init__.py

@@ -0,0 +1,7 @@
+"""
+HTTP client for Reality Defender API interaction
+"""
+
+from .http_client import create_http_client
+
+__all__ = ["create_http_client"]

realitydefender/client/http_client.py

@@ -0,0 +1,178 @@
+"""
+HTTP client for making requests to the Reality Defender API
+"""
+
+import json
+from typing import Any, Dict, Optional, Tuple, TypedDict
+
+import aiohttp
+
+from ..core.constants import DEFAULT_API_ENDPOINT
+from ..errors import RealityDefenderError
+
+
+class ClientConfig(TypedDict, total=False):
+    """Configuration for HTTP client"""
+
+    api_key: str
+    base_url: Optional[str]
+
+
+class HttpClient:
+    """
+    HTTP client for Reality Defender API
+    """
+
+    def __init__(self, config: ClientConfig):
+        """
+        Initialize the HTTP client
+
+        Args:
+            config: Configuration including API key and base URL
+        """
+        self.api_key = config["api_key"]
+        self.base_url = config.get("base_url") or DEFAULT_API_ENDPOINT
+        self.session: Optional[aiohttp.ClientSession] = None
+
+    async def ensure_session(self) -> aiohttp.ClientSession:
+        """
+        Ensure an HTTP session exists or create one
+
+        Returns:
+            Active aiohttp.ClientSession
+        """
+        if self.session is None or self.session.closed:
+            self.session = aiohttp.ClientSession(
+                headers={
+                    "X-API-KEY": self.api_key,
+                    "Accept": "application/json",
+                }
+            )
+        return self.session
+
+    async def get(
+        self, path: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Make a GET request to the API
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            RealityDefenderError: If the request fails
+        """
+        session = await self.ensure_session()
+        url = f"{self.base_url}{path}"
+
+        try:
+            async with session.get(url, params=params) as response:
+                return await self._handle_response(response)
+        except aiohttp.ClientError as e:
+            raise RealityDefenderError(f"HTTP request failed: {str(e)}", "server_error")
+
+    async def post(
+        self,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Tuple[str, bytes, str]]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make a POST request to the API
+
+        Args:
+            path: API endpoint path
+            data: Request body data
+            files: Files to upload
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            RealityDefenderError: If the request fails
+        """
+        session = await self.ensure_session()
+        url = f"{self.base_url}{path}"
+
+        form_data = aiohttp.FormData()
+
+        # Add regular data
+        if data:
+            for key, value in data.items():
+                form_data.add_field(key, str(value))
+
+        # Add files
+        if files:
+            for field_name, (filename, content, content_type) in files.items():
+                form_data.add_field(
+                    field_name, content, filename=filename, content_type=content_type
+                )
+
+        try:
+            async with session.post(url, data=form_data) as response:
+                return await self._handle_response(response)
+        except aiohttp.ClientError as e:
+            raise RealityDefenderError(f"HTTP request failed: {str(e)}", "server_error")
+
+    async def _handle_response(
+        self, response: aiohttp.ClientResponse
+    ) -> Dict[str, Any]:
+        """
+        Handle HTTP response and check for errors
+
+        Args:
+            response: HTTP response from aiohttp
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            RealityDefenderError: If the response contains an error
+        """
+        if response.status == 404:
+            raise RealityDefenderError("Resource not found", "not_found")
+
+        if response.status == 401:
+            raise RealityDefenderError(
+                "Unauthorized - check your API key", "unauthorized"
+            )
+
+        if response.status >= 400:
+            try:
+                error_data = await response.json()
+                message = error_data.get("error", {}).get("message", "Unknown error")
+                raise RealityDefenderError(f"API error: {message}", "server_error")
+            except json.JSONDecodeError:
+                error_text = await response.text()
+                raise RealityDefenderError(f"API error: {error_text}", "server_error")
+
+        try:
+            result: Dict[str, Any] = await response.json()
+            return result
+        except json.JSONDecodeError:
+            content = await response.text()
+            raise RealityDefenderError(
+                f"Invalid JSON response: {content}", "server_error"
+            )
+
+    async def close(self) -> None:
+        """Close the HTTP session if it exists"""
+        if self.session and not self.session.closed:
+            await self.session.close()
+
+
+def create_http_client(config: ClientConfig) -> HttpClient:
+    """
+    Create a new HTTP client for the Reality Defender API
+
+    Args:
+        config: Client configuration including API key
+
+    Returns:
+        Configured HTTP client
+    """
+    return HttpClient(config)

realitydefender/core/constants.py

@@ -0,0 +1,21 @@
+"""
+Constants used across the Reality Defender SDK
+"""
+
+# Default API endpoint
+DEFAULT_API_ENDPOINT = "https://api.prd.realitydefender.xyz"
+
+# API paths
+API_PATHS = {
+    "SIGNED_URL": "/api/files/aws-presigned",
+    "MEDIA_RESULT": "/api/media/users",
+}
+
+# Default polling interval in milliseconds
+DEFAULT_POLLING_INTERVAL = 2000
+
+# Default timeout in milliseconds (1 minute)
+DEFAULT_TIMEOUT = 60000
+
+# Default maximum polling attempts
+DEFAULT_MAX_ATTEMPTS = 30

realitydefender/core/events.py

@@ -0,0 +1,124 @@
+"""
+Event handling for asynchronous operations
+"""
+
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Union, overload
+
+from ..types.events import ErrorHandler, EventName, ResultHandler
+
+# Create a generic type for event names that can be either the specific EventName type
+# or any string (for testing purposes)
+E = TypeVar('E', EventName, str)
+CallbackT = TypeVar('CallbackT', bound=Callable[..., Any])
+
+
+class EventEmitter:
+    """
+    Simple event emitter for handling callbacks and events
+    """
+
+    def __init__(self) -> None:
+        """Initialize the event emitter with empty event handlers"""
+        self._events: Dict[str, List[Callable]] = {}
+
+    @overload
+    def on(self, event: EventName, callback: Union[ResultHandler, ErrorHandler]) -> None: ...
+
+    @overload
+    def on(self, event: str, callback: Callable[..., Any]) -> None: ...
+
+    def on(self, event: str, callback: Callable[..., Any]) -> None:
+        """
+        Register an event handler
+
+        Args:
+            event: Event name to listen for
+            callback: Function to call when event occurs
+        """
+        if event not in self._events:
+            self._events[event] = []
+        self._events[event].append(callback)
+
+    @overload
+    def once(self, event: EventName, callback: Union[ResultHandler, ErrorHandler]) -> None: ...
+
+    @overload
+    def once(self, event: str, callback: Callable[..., Any]) -> None: ...
+
+    def once(self, event: str, callback: Callable[..., Any]) -> None:
+        """
+        Register an event handler that will be removed after being called once
+
+        Args:
+            event: Event name to listen for
+            callback: Function to call when event occurs
+        """
+
+        def one_time_handler(*args: Any, **kwargs: Any) -> Any:
+            self.remove_listener(event, one_time_handler)
+            return callback(*args, **kwargs)
+
+        self.on(event, one_time_handler)
+
+    @overload
+    def emit(self, event: EventName, *args: Any, **kwargs: Any) -> bool: ...
+
+    @overload
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> bool: ...
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> bool:
+        """
+        Emit an event with arguments
+
+        Args:
+            event: Event name to emit
+            *args: Arguments to pass to event handlers
+            **kwargs: Keyword arguments to pass to event handlers
+
+        Returns:
+            True if the event had listeners, False otherwise
+        """
+        if event not in self._events:
+            return False
+
+        for callback in self._events[event]:
+            callback(*args, **kwargs)
+
+        return len(self._events[event]) > 0
+
+    @overload
+    def remove_listener(self, event: EventName, callback: Callable[..., Any]) -> None: ...
+
+    @overload
+    def remove_listener(self, event: str, callback: Callable[..., Any]) -> None: ...
+
+    def remove_listener(self, event: str, callback: Callable[..., Any]) -> None:
+        """
+        Remove a specific event listener
+
+        Args:
+            event: Event name
+            callback: Function to remove
+        """
+        if event not in self._events:
+            return
+
+        self._events[event] = [cb for cb in self._events[event] if cb != callback]
+
+    @overload
+    def remove_all_listeners(self, event: Optional[EventName] = None) -> None: ...
+
+    @overload
+    def remove_all_listeners(self, event: Optional[str] = None) -> None: ...
+
+    def remove_all_listeners(self, event: Optional[str] = None) -> None:
+        """
+        Remove all listeners for an event or all events
+
+        Args:
+            event: Event name, or None to remove all events
+        """
+        if event is not None:
+            self._events[event] = []
+        else:
+            self._events = {}