"""
This type stub file was generated by pyright.
"""

import io
import numpy.typing as npt
from collections.abc import Sequence
from enum import IntEnum
from pathlib import Path
from typing import Any, Final, Literal, TYPE_CHECKING, Union
from typing_extensions import TypeAlias
from PIL import GifImagePlugin, Image, ImageFile
from streamlit.proto.Image_pb2 import ImageList as ImageListProto

if TYPE_CHECKING:
    ...
PILImage: TypeAlias = Union["ImageFile.ImageFile", "Image.Image", "GifImagePlugin.GifImageFile"]
AtomicImage: TypeAlias = Union[PILImage, "npt.NDArray[Any]", io.BytesIO, str, Path, bytes]
Channels: TypeAlias = Literal["RGB", "BGR"]
ImageFormat: TypeAlias = Literal["JPEG", "PNG", "GIF"]
ImageFormatOrAuto: TypeAlias = Literal[ImageFormat, "auto"]
ImageOrImageList: TypeAlias = Union[AtomicImage, Sequence[AtomicImage]]
MAXIMUM_CONTENT_WIDTH: Final[int] = ...
class WidthBehavior(IntEnum):
    """
    Special values that are recognized by the frontend and allow us to change the
    behavior of the displayed image.
    """
    ORIGINAL = ...
    COLUMN = ...
    AUTO = ...
    MIN_IMAGE_OR_CONTAINER = ...
    MAX_IMAGE_OR_CONTAINER = ...


def image_to_url(image: AtomicImage, width: int, clamp: bool, channels: Channels, output_format: ImageFormatOrAuto, image_id: str) -> str:
    """Return a URL that an image can be served from.
    If `image` is already a URL, return it unmodified.
    Otherwise, add the image to the MediaFileManager and return the URL.
    (When running in "raw" mode, we won't actually load data into the
    MediaFileManager, and we'll return an empty URL).
    """
    ...

def marshall_images(coordinates: str, image: ImageOrImageList, caption: str | npt.NDArray[Any] | list[str] | None, width: int | WidthBehavior, proto_imgs: ImageListProto, clamp: bool, channels: Channels = ..., output_format: ImageFormatOrAuto = ...) -> None:
    """Fill an ImageListProto with a list of images and their captions.
    The images will be resized and reformatted as necessary.

    Parameters
    ----------
    coordinates
        A string indentifying the images' location in the frontend.
    image
        The image or images to include in the ImageListProto.
    caption
        Image caption. If displaying multiple images, caption should be a
        list of captions (one for each image).
    width
        The desired width of the image or images. This parameter will be
        passed to the frontend.
        Positive values set the image width explicitly.
        Negative values has some special. For details, see: `WidthBehaviour`
    proto_imgs
        The ImageListProto to fill in.
    clamp
        Clamp image pixel values to a valid range ([0-255] per channel).
        This is only meaningful for byte array images; the parameter is
        ignored for image URLs. If this is not set, and an image has an
        out-of-range value, an error will be thrown.
    channels
        If image is an nd.array, this parameter denotes the format used to
        represent color information. Defaults to 'RGB', meaning
        `image[:, :, 0]` is the red channel, `image[:, :, 1]` is green, and
        `image[:, :, 2]` is blue. For images coming from libraries like
        OpenCV you should set this to 'BGR', instead.
    output_format
        This parameter specifies the format to use when transferring the
        image data. Photos should use the JPEG format for lossy compression
        while diagrams should use the PNG format for lossless compression.
        Defaults to 'auto' which identifies the compression type based
        on the type and format of the image argument.
    """
    ...

