"""Async restore job management protocol."""

from typing import TYPE_CHECKING, Protocol, runtime_checkable

from pinecone.__interface__.restore_jobs.info import RestoreJobInfoProtocol


if TYPE_CHECKING:
    from pinecone.models.pagination import AsyncPaginator


@runtime_checkable
class AsyncRestoreJobNamespaceProtocol(Protocol):
    """Protocol for async restore job management operations.

    Restore jobs are created automatically when restoring an index from a backup.
    This namespace provides async read-only access to monitor restore job progress.

    Example:
        >>> from pinecone import AsyncPinecone
        >>> import asyncio
        >>>
        >>> async def main():
        ...     async with AsyncPinecone(api_key="...") as pc:
        ...         # List all restore jobs
        ...         async for job in pc.restore_jobs.list():
        ...             print(f"{job.restore_job_id}: {job.status}")
        >>>
        >>> asyncio.run(main())
    """

    def list(
        self,
        *,
        limit: int | None = None,
        pagination_token: str | None = None,
    ) -> "AsyncPaginator[RestoreJobInfoProtocol]":
        """List all restore jobs in the project asynchronously.

        Args:
            limit: Maximum number of items to return (across all pages).
            pagination_token: Token to resume pagination from a previous call.

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

        Example:
            >>> # List all restore jobs
            >>> async for job in pc.restore_jobs.list():
            ...     print(f"{job.restore_job_id}: {job.status}")

        Example with pagination:
            >>> async for page in pc.restore_jobs.list().pages():
            ...     print(f"Got {len(page.items)} jobs")
        """
        ...

    async def describe(self, job_id: str) -> RestoreJobInfoProtocol:
        """Get details of a specific restore job asynchronously.

        Args:
            job_id: Unique identifier of the restore job.

        Returns:
            RestoreJobInfo with complete job metadata.

        Raises:
            ValueError: If job_id is empty.
            PineconeException: If job not found or operation fails.

        Example:
            >>> job = await pc.restore_jobs.describe("670e8400-e29b-41d4-a716-446655440001")
            >>> print(f"Status: {job.status}")
            >>> print(f"Progress: {job.percent_complete}%")
            >>> if job.completed_at:
            ...     print(f"Completed: {job.completed_at}")
        """
        ...
