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

import dataclasses
from abc import ABC, abstractmethod
from io import BytesIO, StringIO, TextIOBase
from pathlib import Path
from typing import Any, AnyStr, Generic, IO, Literal, TypeVar, overload
from pandas._typing import BaseBuffer, CompressionDict, CompressionOptions, FilePath, ReadBuffer, StorageOptions, WriteBuffer
from pandas.util._decorators import doc
from pandas.core.shared_docs import _shared_docs

"""Common IO api utilities"""
_VALID_URLS = ...
_RFC_3986_PATTERN = ...
BaseBufferT = TypeVar("BaseBufferT", bound=BaseBuffer)
@dataclasses.dataclass
class IOArgs:
    """
    Return value of io/common.py:_get_filepath_or_buffer.
    """
    filepath_or_buffer: str | BaseBuffer
    encoding: str
    mode: str
    compression: CompressionDict
    should_close: bool = ...


@dataclasses.dataclass
class IOHandles(Generic[AnyStr]):
    """
    Return value of io/common.py:get_handle

    Can be used as a context manager.

    This is used to easily close created buffers and to handle corner cases when
    TextIOWrapper is inserted.

    handle: The file handle to be used.
    created_handles: All file handles that are created by get_handle
    is_wrapped: Whether a TextIOWrapper needs to be detached.
    """
    handle: IO[AnyStr]
    compression: CompressionDict
    created_handles: list[IO[bytes] | IO[str]] = ...
    is_wrapped: bool = ...
    def close(self) -> None:
        """
        Close all created buffers.

        Note: If a TextIOWrapper was inserted, it is flushed and detached to
        avoid closing the potentially user-created buffer.
        """
        ...
    
    def __enter__(self) -> IOHandles[AnyStr]:
        ...
    
    def __exit__(self, *args: Any) -> None:
        ...
    


def is_url(url: object) -> bool:
    """
    Check to see if a URL has a valid protocol.

    Parameters
    ----------
    url : str or unicode

    Returns
    -------
    isurl : bool
        If `url` has a valid protocol return True otherwise False.
    """
    ...

def validate_header_arg(header: object) -> None:
    ...

@overload
def stringify_path(filepath_or_buffer: FilePath, convert_file_like: bool = ...) -> str:
    ...

@overload
def stringify_path(filepath_or_buffer: BaseBufferT, convert_file_like: bool = ...) -> BaseBufferT:
    ...

def stringify_path(filepath_or_buffer: FilePath | BaseBufferT, convert_file_like: bool = ...) -> str | BaseBufferT:
    """
    Attempt to convert a path-like object to a string.

    Parameters
    ----------
    filepath_or_buffer : object to be converted

    Returns
    -------
    str_filepath_or_buffer : maybe a string version of the object

    Notes
    -----
    Objects supporting the fspath protocol (python 3.6+) are coerced
    according to its __fspath__ method.

    Any other object is passed through unchanged, which includes bytes,
    strings, buffers, or anything else that's not even path-like.
    """
    ...

def urlopen(*args, **kwargs): # -> _UrlopenRet:
    """
    Lazy-import wrapper for stdlib urlopen, as that imports a big chunk of
    the stdlib.
    """
    ...

def is_fsspec_url(url: FilePath | BaseBuffer) -> bool:
    """
    Returns true if the given URL looks like
    something fsspec can handle
    """
    ...

def file_path_to_url(path: str) -> str:
    """
    converts an absolute native path to a FILE URL.

    Parameters
    ----------
    path : a path in native format

    Returns
    -------
    a valid FILE URL
    """
    ...

_extension_to_compression = ...
_supported_compressions = ...
def get_compression_method(compression: CompressionOptions) -> tuple[str | None, CompressionDict]:
    """
    Simplifies a compression argument to a compression method string and
    a mapping containing additional arguments.

    Parameters
    ----------
    compression : str or mapping
        If string, specifies the compression method. If mapping, value at key
        'method' specifies compression method.

    Returns
    -------
    tuple of ({compression method}, Optional[str]
              {compression arguments}, Dict[str, Any])

    Raises
    ------
    ValueError on mapping missing 'method' key
    """
    ...

@doc(compression_options=_shared_docs["compression_options"] % "filepath_or_buffer")
def infer_compression(filepath_or_buffer: FilePath | BaseBuffer, compression: str | None) -> str | None:
    """
    Get the compression method for filepath_or_buffer. If compression='infer',
    the inferred compression method is returned. Otherwise, the input
    compression method is returned unchanged, unless it's invalid, in which
    case an error is raised.

    Parameters
    ----------
    filepath_or_buffer : str or file handle
        File path or object.
    {compression_options}

        .. versionchanged:: 1.4.0 Zstandard support.

    Returns
    -------
    string or None

    Raises
    ------
    ValueError on invalid compression specified.
    """
    ...

def check_parent_directory(path: Path | str) -> None:
    """
    Check if parent directory of a file exists, raise OSError if it does not

    Parameters
    ----------
    path: Path or str
        Path to check parent directory of
    """
    ...

@overload
def get_handle(path_or_buf: FilePath | BaseBuffer, mode: str, *, encoding: str | None = ..., compression: CompressionOptions = ..., memory_map: bool = ..., is_text: Literal[False], errors: str | None = ..., storage_options: StorageOptions = ...) -> IOHandles[bytes]:
    ...

@overload
def get_handle(path_or_buf: FilePath | BaseBuffer, mode: str, *, encoding: str | None = ..., compression: CompressionOptions = ..., memory_map: bool = ..., is_text: Literal[True] = ..., errors: str | None = ..., storage_options: StorageOptions = ...) -> IOHandles[str]:
    ...

@overload
def get_handle(path_or_buf: FilePath | BaseBuffer, mode: str, *, encoding: str | None = ..., compression: CompressionOptions = ..., memory_map: bool = ..., is_text: bool = ..., errors: str | None = ..., storage_options: StorageOptions = ...) -> IOHandles[str] | IOHandles[bytes]:
    ...

@doc(compression_options=_shared_docs["compression_options"] % "path_or_buf")
def get_handle(path_or_buf: FilePath | BaseBuffer, mode: str, *, encoding: str | None = ..., compression: CompressionOptions = ..., memory_map: bool = ..., is_text: bool = ..., errors: str | None = ..., storage_options: StorageOptions = ...) -> IOHandles[str] | IOHandles[bytes]:
    """
    Get file handle for given path/buffer and mode.

    Parameters
    ----------
    path_or_buf : str or file handle
        File path or object.
    mode : str
        Mode to open path_or_buf with.
    encoding : str or None
        Encoding to use.
    {compression_options}

        .. versionchanged:: 1.0.0
           May now be a dict with key 'method' as compression mode
           and other keys as compression options if compression
           mode is 'zip'.

        .. versionchanged:: 1.1.0
           Passing compression options as keys in dict is now
           supported for compression modes 'gzip', 'bz2', 'zstd' and 'zip'.

        .. versionchanged:: 1.4.0 Zstandard support.

    memory_map : bool, default False
        See parsers._parser_params for more information. Only used by read_csv.
    is_text : bool, default True
        Whether the type of the content passed to the file/buffer is string or
        bytes. This is not the same as `"b" not in mode`. If a string content is
        passed to a binary file/buffer, a wrapper is inserted.
    errors : str, default 'strict'
        Specifies how encoding and decoding errors are to be handled.
        See the errors argument for :func:`open` for a full list
        of options.
    storage_options: StorageOptions = None
        Passed to _get_filepath_or_buffer

    .. versionchanged:: 1.2.0

    Returns the dataclass IOHandles
    """
    ...

class _BufferedWriter(BytesIO, ABC):
    """
    Some objects do not support multiple .write() calls (TarFile and ZipFile).
    This wrapper writes to the underlying buffer on close.
    """
    @abstractmethod
    def write_to_buffer(self) -> None:
        ...
    
    def close(self) -> None:
        ...
    


class _BytesTarFile(_BufferedWriter):
    def __init__(self, name: str | None = ..., mode: Literal["r", "a", "w", "x"] = ..., fileobj: ReadBuffer[bytes] | WriteBuffer[bytes] | None = ..., archive_name: str | None = ..., **kwargs) -> None:
        ...
    
    def extend_mode(self, mode: str) -> str:
        ...
    
    def infer_filename(self) -> str | None:
        """
        If an explicit archive_name is not given, we still want the file inside the zip
        file not to be named something.tar, because that causes confusion (GH39465).
        """
        ...
    
    def write_to_buffer(self) -> None:
        ...
    


class _BytesZipFile(_BufferedWriter):
    def __init__(self, file: FilePath | ReadBuffer[bytes] | WriteBuffer[bytes], mode: str, archive_name: str | None = ..., **kwargs) -> None:
        ...
    
    def infer_filename(self) -> str | None:
        """
        If an explicit archive_name is not given, we still want the file inside the zip
        file not to be named something.zip, because that causes confusion (GH39465).
        """
        ...
    
    def write_to_buffer(self) -> None:
        ...
    


class _IOWrapper:
    def __init__(self, buffer: BaseBuffer) -> None:
        ...
    
    def __getattr__(self, name: str): # -> Any:
        ...
    
    def readable(self) -> bool:
        ...
    
    def seekable(self) -> bool:
        ...
    
    def writable(self) -> bool:
        ...
    


class _BytesIOWrapper:
    def __init__(self, buffer: StringIO | TextIOBase, encoding: str = ...) -> None:
        ...
    
    def __getattr__(self, attr: str): # -> Any:
        ...
    
    def read(self, n: int | None = ...) -> bytes:
        ...
    


def file_exists(filepath_or_buffer: FilePath | BaseBuffer) -> bool:
    """Test whether file exists."""
    ...

