"""Backup management protocol."""

from typing import TYPE_CHECKING, Protocol, runtime_checkable

from pinecone.__interface__.backups.info import BackupInfoProtocol


if TYPE_CHECKING:
    from pinecone.models.pagination import Paginator


@runtime_checkable
class BackupNamespaceProtocol(Protocol):
    """Protocol for backup management operations.

    Example:
        >>> from pinecone import Pinecone
        >>> pc = Pinecone(api_key="...")
        >>>
        >>> # Create backup
        >>> backup = pc.backups.create(
        ...     index_name="my-index", name="my-backup", description="Monthly backup"
        ... )
        >>>
        >>> # List backups
        >>> backups = pc.backups.list()
    """

    def list(
        self,
        *,
        index_name: str | None = None,
        limit: int | None = None,
        pagination_token: str | None = None,
    ) -> "Paginator[BackupInfoProtocol]":
        """List backups for a project or specific index.

        Args:
            index_name: Optional index name to filter backups. If None, lists all
                backups in the project.
            limit: Maximum number of items to return (across all pages).
            pagination_token: Token to resume pagination from a previous call.

        Returns:
            Paginator over BackupInfo objects. Iterate directly for items,
            or use .pages() for page-level access.

        Example:
            >>> # List all backups in project
            >>> for backup in pc.backups.list():
            ...     print(f"{backup.backup_id}: {backup.status}")

        Example filtering by index:
            >>> # List backups for specific index
            >>> for backup in pc.backups.list(index_name="my-index"):
            ...     print(f"{backup.name}: {backup.status}")

        Example with page-level access:
            >>> for page in pc.backups.list().pages():
            ...     print(f"Got {len(page.items)} backups")
        """
        ...

    def create(
        self,
        index_name: str,
        *,
        name: str | None = None,
        description: str | None = None,
        timeout: float | None = None,
    ) -> BackupInfoProtocol:
        """Create a backup from a serverless index.

        Args:
            index_name: Name of the index to back up.
            name: Optional user-defined name for the backup.
            description: Optional description providing context for the backup.
            timeout: Optional request timeout in seconds.

        Returns:
            BackupInfo with backup metadata including backup_id and status.

        Raises:
            ValueError: If index_name is empty.
            PineconeException: If backup creation fails.

        Example:
            >>> backup = pc.backups.create(
            ...     index_name="my-index",
            ...     name="example-backup",
            ...     description="Monthly backup of production index",
            ... )
            >>> print(f"Backup ID: {backup.backup_id}")
            >>> print(f"Status: {backup.status}")
        """
        ...

    def delete(self, backup_id: str) -> None:
        """Delete a backup.

        Args:
            backup_id: Unique identifier of the backup to delete.

        Raises:
            ValueError: If backup_id is empty.
            PineconeException: If deletion fails.

        Example:
            >>> pc.backups.delete("8c85e612-ed1c-4f97-9f8c-8194e07bcf71")
        """
        ...

    def describe(self, backup_id: str) -> BackupInfoProtocol:
        """Get backup details.

        Args:
            backup_id: Unique identifier of the backup.

        Returns:
            BackupInfo with complete backup metadata.

        Raises:
            ValueError: If backup_id is empty.
            PineconeException: If backup not found or operation fails.

        Example:
            >>> info = pc.backups.describe("8c85e612-ed1c-4f97-9f8c-8194e07bcf71")
            >>> print(f"Status: {info.status}")
            >>> print(f"Size: {info.size_bytes} bytes")
            >>> print(f"Records: {info.record_count}")
        """
        ...
