"""Utilities.

Miscellaneous utilities.
"""

# Author: Eric Larson
# License: 3-clause BSD

import hashlib
import json
import os
import re
import subprocess
import zipfile
from functools import partial
from pathlib import Path
from shutil import copyfile, move
from typing import Any, Callable, Iterator, Literal, Tuple

import sphinx.util

try:
    from sphinx.util.display import status_iterator  # noqa: F401
except Exception:  # Sphinx < 6
    from sphinx.util import status_iterator  # type: ignore[no-redef]  # noqa: F401

from .typing import GalleryConfig

logger = sphinx.util.logging.getLogger("sphinx-gallery")


# Text writing kwargs for builtins.open
_W_KW = dict(encoding="utf-8", newline="\n")


def scale_image(in_fname: str, out_fname: str, max_width: int, max_height: int) -> None:
    """Scales image centered in image box using `max_width` and `max_height`.

    The same aspect ratio is retained. If `in_fname` == `out_fname` the image can only
    be scaled down.
    """
    # local import to avoid testing dependency on PIL:
    from PIL import Image

    img = Image.open(in_fname)
    # XXX someday we should just try img.thumbnail((max_width, max_height)) ...
    width_in, height_in = img.size
    scale_w = max_width / float(width_in)
    scale_h = max_height / float(height_in)

    if height_in * scale_w <= max_height:
        scale = scale_w
    else:
        scale = scale_h

    if scale >= 1.0 and in_fname == out_fname:
        return

    width_sc = int(round(scale * width_in))
    height_sc = int(round(scale * height_in))

    # resize the image using resize; if using .thumbnail and the image is
    # already smaller than max_width, max_height, then this won't scale up
    # at all (maybe could be an option someday...)
    bicubic = Image.Resampling.BICUBIC
    img = img.resize((width_sc, height_sc), bicubic)
    # img.thumbnail((width_sc, height_sc), Image.BICUBIC)
    # width_sc, height_sc = img.size  # necessary if using thumbnail

    # insert centered
    thumb = Image.new("RGBA", (max_width, max_height), (255, 255, 255, 0))
    pos_insert = ((max_width - width_sc) // 2, (max_height - height_sc) // 2)
    thumb.paste(img, pos_insert)

    try:
        thumb.save(out_fname)
    except OSError:
        # try again, without the alpha channel (e.g., for JPEG)
        thumb.convert("RGB").save(out_fname)


def optipng(fname: str, args: Tuple = ()) -> None:
    """Optimize a PNG in place.

    Parameters
    ----------
    fname : str
        The filename. If it ends with '.png', ``optipng -o7 fname`` will
        be run. If it fails because the ``optipng`` executable is not found
        or optipng fails, the function returns.
    args : tuple
        Extra command-line arguments, such as ``['-o7']``.
    """
    fname = str(fname)
    if fname.endswith(".png"):
        # -o7 because this is what CPython used
        # https://github.com/python/cpython/pull/8032
        try:
            subprocess.check_call(
                ["optipng"] + list(args) + [fname],
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
            )
        except (subprocess.CalledProcessError, OSError):  # FileNotFoundError
            pass


def _has_optipng() -> bool:
    try:
        subprocess.check_call(
            ["optipng", "--version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE
        )
    except OSError:  # FileNotFoundError
        return False
    else:
        return True


def get_md5sum(src_file: str | os.PathLike, mode: Literal["t", "b"] = "b") -> str:
    """Returns md5sum of file.

    Parameters
    ----------
    src_file : str | os.PathLike
        Filename to get md5sum for.
    mode : 't' or 'b'
        File mode to open file with. When in text mode, universal line endings
        are used to ensure consistency in hashes between platforms.
    """
    # Universal newline mode is intentional here for text mode
    assert mode in ("t", "b")
    if mode == "t":
        with open(
            src_file, "rt", errors="surrogateescape", encoding="utf-8"
        ) as src_data:
            src_content = src_data.read().encode(
                errors="surrogateescape", encoding="utf-8"
            )
            return hashlib.md5(src_content).hexdigest()
    else:
        with open(src_file, "rb") as src_data:
            src_content = src_data.read()
            return hashlib.md5(src_content).hexdigest()


def _replace_md5(
    fname_new: str | os.PathLike,
    fname_old: str | os.PathLike | None = None,
    *,
    method: Literal["move", "copy"] = "move",
    mode: Literal["t", "b"] = "b",
    check: Literal["md5", "json"] = "md5",
) -> None:
    fname_new = str(fname_new)  # convert possible Path
    assert method in ("move", "copy")
    if fname_old is None:
        assert fname_new.endswith(".new")
        fname_old = os.path.splitext(fname_new)[0]
    replace = True
    if os.path.isfile(fname_old):
        func: Callable[[str], str]
        if check == "md5":  # default
            func = partial(get_md5sum, mode=mode)
        else:
            assert check == "json"

            def func(x):
                return json.loads(Path(x).read_text("utf-8"))

        try:
            equiv = func(fname_old) == func(fname_new)
        except Exception:  # e.g., old JSON file is a problem
            equiv = False
        if equiv:
            replace = False
            if method == "move":
                os.remove(fname_new)
        else:
            logger.debug(f"Replacing stale {fname_old} with {fname_new}")
    if replace:
        if method == "move":
            move(fname_new, fname_old)
        else:
            copyfile(fname_new, fname_old)
    assert os.path.isfile(fname_old)


def iter_gallery_header_filenames(gallery_conf: GalleryConfig) -> Iterator[str]:
    """
    A generator of all possible gallery header filenames.

    We support GALLERY_HEADER.[ext], and for backward-compatibility README.[ext]
    """
    extensions = [".txt"] + sorted(gallery_conf["source_suffix"])
    for ext in extensions:
        for fname in ("GALLERY_HEADER", "README", "readme"):
            yield fname + ext


def check_duplicate_filenames(files: list[str]) -> None:
    """Check for duplicate filenames across gallery directories."""
    # Check whether we'll have duplicates
    used_names = set()
    dup_names = list()

    for this_file in files:
        this_fname = os.path.basename(this_file)
        if this_fname in used_names:
            dup_names.append(this_file)
        else:
            used_names.add(this_fname)

    if len(dup_names) > 0:
        logger.warning(
            "Duplicate example file name(s) found. Having duplicate file "
            "names will break some links. "
            "List of files: %s",
            sorted(dup_names),
        )


def check_spaces_in_filenames(files: list[str]) -> None:
    """Check for spaces in filenames across example directories."""
    regex = re.compile(r"[\s]")
    files_with_space = list(filter(regex.search, files))
    if files_with_space:
        logger.warning(
            "Example file name(s) with spaces found. Having spaces in "
            "file names will break some links. "
            "List of files: %s",
            sorted(files_with_space),
        )


def _collect_gallery_files(
    examples_dirs: list[str],
    gallery_conf: GalleryConfig,
    check_filenames: bool = False,
) -> list[str]:
    """Collect files with `example_extensions`, accounting for `ignore_pattern`.

    If `check_filenames` we check one level of sub-folders as well as root
    `example_dirs` for gallery example files. We then check for duplicate and
    spaces in full file paths.
    """
    exts = gallery_conf["example_extensions"]
    max_depth = 1 if check_filenames else 0
    files = []
    gallery_header_filenames = list(iter_gallery_header_filenames(gallery_conf))
    for example_dir in examples_dirs:
        example_depth = os.path.abspath(example_dir).count(os.sep)
        for root, _, filenames in os.walk(example_dir):
            root = os.path.normpath(root)
            if (root.count(os.sep) - example_depth) > max_depth:
                break
            for filename in filenames:
                if filename in gallery_header_filenames:
                    continue
                if (s := Path(filename).suffix) and s in exts:
                    if re.search(gallery_conf["ignore_pattern"], filename) is None:
                        file = filename
                        if check_filenames:
                            file = os.path.join(root, filename)
                        files.append(file)
    if check_filenames:
        check_duplicate_filenames(files)
        check_spaces_in_filenames(files)
    return files


def zip_files(
    file_list: list[str], zipname: str, relative_to: str, extension: str | None = None
) -> str:
    """
    Creates a zip file with the given files.

    A zip file named `zipname` will be created containing the files listed in
    `file_list`. The zip file contents will be stored with their paths stripped to be
    relative to `relative_to`.
    """
    zipname_new = str(zipname) + ".new"
    with zipfile.ZipFile(zipname_new, mode="w") as zipf:
        for fname in file_list:
            if extension is not None:
                fname = os.path.splitext(fname)[0] + extension
            zipf.write(fname, os.path.relpath(fname, relative_to))
    _replace_md5(zipname_new)
    return zipname


def _has_pypandoc() -> Tuple[bool | None, str | None]:
    """Check if pypandoc package available."""
    try:
        import pypandoc  # noqa

        # Import error raised only when function called
        version = pypandoc.get_pandoc_version()
    except (ImportError, OSError):
        return None, None
    else:
        return True, version


def _has_graphviz() -> bool:
    try:
        import graphviz  # noqa F401
    except ImportError as exc:
        logger.info(
            "`graphviz` required for graphical visualization "
            f"but could not be imported, got: {exc}"
        )
        return False
    return True


def _format_toctree(items: list[str], includehidden: bool = False) -> str:
    """Format a toc tree."""
    st = """
.. toctree::
   :hidden:"""
    if includehidden:
        st += """
   :includehidden:
"""
    st += """

   {}\n""".format("\n   ".join(items))

    st += "\n"

    return st


# Should be matched with `_read_json`
def _write_json(target_file: Path, to_save: dict, name: str = "") -> None:
    """Write dictionary to JSON file."""
    codeobj_fname = Path(target_file).with_name(target_file.stem + f"{name}.json.new")
    with open(codeobj_fname, "w", **_W_KW) as fid:  # type: ignore[call-overload]
        json.dump(
            to_save,
            fid,
            sort_keys=True,
            ensure_ascii=False,
            indent=1,
            check_circular=False,
        )
    _replace_md5(codeobj_fname, check="json")


def _read_json(json_fname: str | Path) -> Any:
    """Read JSON dictionary from file."""
    with open(json_fname, "r", encoding="utf-8") as fid:
        json_dict = json.load(fid)
    return json_dict


def _combine_backreferences(dict_a: dict, dict_b: dict | None) -> dict:
    """Combine backreferences dictionaries, joining lists when keys are the same."""
    # `dict_b` is None when `backreferences_dir` config not set
    if isinstance(dict_b, dict):
        for key, value in dict_b.items():
            dict_a.setdefault(key, []).extend(value)
    return dict_a
