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

import contextlib
import os
from typing import Any, TYPE_CHECKING
from collections.abc import Iterator

"""Operating system-related utility functions for Sphinx."""
if TYPE_CHECKING:
    ...
SEP = ...
def os_path(canonical_path: str, /) -> str:
    ...

def canon_path(native_path: str | os.PathLike[str], /) -> str:
    """Return path in OS-independent form"""
    ...

def path_stabilize(filepath: str | os.PathLike[str], /) -> str:
    "Normalize path separator and unicode string"
    ...

def relative_uri(base: str, to: str) -> str:
    """Return a relative URL from ``base`` to ``to``."""
    ...

def ensuredir(file: str | os.PathLike[str]) -> None:
    """Ensure that a path exists."""
    ...

def mtimes_of_files(dirnames: list[str], suffix: str) -> Iterator[float]:
    ...

def copytimes(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
    """Copy a file's modification times."""
    ...

def copyfile(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
    """Copy a file and its modification times, if possible.

    Note: ``copyfile`` skips copying if the file has not been changed"""
    ...

no_fn_re = ...
project_suffix_re = ...
def make_filename(string: str) -> str:
    ...

def make_filename_from_project(project: str) -> str:
    ...

def relpath(path: str | os.PathLike[str], start: str | os.PathLike[str] | None = ...) -> str:
    """Return a relative filepath to *path* either from the current directory or
    from an optional *start* directory.

    This is an alternative of ``os.path.relpath()``.  This returns original path
    if *path* and *start* are on different drives (for Windows platform).
    """
    ...

safe_relpath = ...
fs_encoding = ...
abspath = ...
class _chdir:
    """Remove this fall-back once support for Python 3.10 is removed."""
    def __init__(self, target_dir: str, /) -> None:
        ...
    
    def __enter__(self): # -> None:
        ...
    
    def __exit__(self, _exc_type, _exc_value, _traceback, /): # -> None:
        ...
    


@contextlib.contextmanager
def cd(target_dir: str) -> Iterator[None]:
    ...

class FileAvoidWrite:
    """File-like object that buffers output and only writes if content changed.

    Use this class like when writing to a file to avoid touching the original
    file if the content hasn't changed. This is useful in scenarios where file
    mtime is used to invalidate caches or trigger new behavior.

    When writing to this file handle, all writes are buffered until the object
    is closed.

    Objects can be used as context managers.
    """
    def __init__(self, path: str) -> None:
        ...
    
    def write(self, data: str) -> None:
        ...
    
    def close(self) -> None:
        """Stop accepting writes and write file, if needed."""
        ...
    
    def __enter__(self) -> FileAvoidWrite:
        ...
    
    def __exit__(self, exc_type: type[Exception], exc_value: Exception, traceback: Any) -> bool:
        ...
    
    def __getattr__(self, name: str) -> Any:
        ...
    


def rmtree(path: str) -> None:
    ...

