"""Collection management protocol."""

from typing import TYPE_CHECKING, Protocol, runtime_checkable

from pinecone.__interface__.collections.info import CollectionInfoProtocol


if TYPE_CHECKING:
    from pinecone.models.pagination import Paginator


@runtime_checkable
class CollectionNamespaceProtocol(Protocol):
    """Protocol for collection management operations.

    Collections are static copies of indexes useful for backups and cloning.

    Example:
        >>> from pinecone import Pinecone
        >>> pc = Pinecone(api_key="...")
        >>>
        >>> # Create collection from index
        >>> pc.collections.create(name="my-collection", source="my-index")
        >>>
        >>> # List collections
        >>> collections = pc.collections.list()
    """

    def list(
        self,
        *,
        limit: int | None = None,
        pagination_token: str | None = None,
    ) -> "Paginator[CollectionInfoProtocol]":
        """List all collections.

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

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

        Example:
            >>> for coll in pc.collections.list():
            ...     print(f"{coll.name}: {coll.vector_count} vectors")

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

    def create(
        self,
        name: str,
        *,
        source: str,
        timeout: int | None = None,
    ) -> None:
        """Create a collection from a pod-based index.

        This operation is asynchronous. The collection is created in the background
        and may take time to complete.

        Args:
            name: Collection name (1-45 chars, lowercase alphanumeric or '-').
            source: Source pod-based index name to create collection from.
            timeout: Optional timeout in seconds for the API request.

        Raises:
            ValueError: If name or source is empty, or timeout is not positive.
            APIError: If creation fails.
            NotFoundError: If source index not found.

        Example:
            >>> pc.collections.create(name="my-backup", source="my-index")
        """
        ...

    def delete(self, name: str, *, timeout: int | None = None) -> None:
        """Delete a collection.

        Args:
            name: Collection name to delete.
            timeout: Optional timeout in seconds for the API request.

        Raises:
            ValueError: If name is empty or timeout is not positive.
            NotFoundError: If collection not found.
            APIError: If deletion fails.

        Example:
            >>> pc.collections.delete("my-backup")
        """
        ...

    def describe(self, name: str) -> CollectionInfoProtocol:
        """Get collection details.

        Args:
            name: Collection name.

        Returns:
            CollectionInfoProtocol with metadata including name, size, status,
            dimension, vector_count, and environment.

        Raises:
            ValueError: If name is empty.
            NotFoundError: If collection not found.
            APIError: If operation fails.

        Example:
            >>> info = pc.collections.describe("my-backup")
            >>> print(f"Status: {info.status}")
            >>> print(f"Vectors: {info.vector_count}")
        """
        ...
