"""
The goal of this module is to provide an idiomatic cross-platform pattern of
accessing platform dependent file systems.

Standard application directory structure: cache, config, and other XDG
standards [XDG_Spec]_. This is similar to the more focused :mod:`appdirs`
module [AS_appdirs]_ (deprecated as of 2023-02-10) and its successor
:mod:`platformdirs` [PlatDirs]_.

Note:
    Table mapping the type of directory to the system default environment
    variable.  Inspired by [SO_43853548]_, [SO_11113974]_, and
    [harawata_appdirs]_.


.. code-block:: none

           | Linux            | Win32          |   Darwin
    data   | $XDG_DATA_HOME   | %APPDATA%      | ~/Library/Application Support
    config | $XDG_CONFIG_HOME | %APPDATA%      | ~/Library/Application Support
    cache  | $XDG_CACHE_HOME  | %LOCALAPPDATA% | ~/Library/Caches


    If an environment variable is not specified the defaults are:
        APPDATA      = ~/AppData/Roaming
        LOCALAPPDATA = ~/AppData/Local

        XDG_DATA_HOME   = ~/.local/share
        XDG_CACHE_HOME  = ~/.cache
        XDG_CONFIG_HOME = ~/.config

References:
    .. [XDG_Spec] https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
    .. [SO_43853548] https://stackoverflow.com/questions/43853548/xdg-windows
    .. [SO_11113974] https://stackoverflow.com/questions/11113974/cross-plat-path
    .. [harawata_appdirs] https://github.com/harawata/appdirs#supported-directories
    .. [AS_appdirs] https://github.com/ActiveState/appdirs
    .. [PlatDirs] https://pypi.org/project/platformdirs/
"""

from __future__ import annotations

import itertools as it
import os
import sys
import typing
from os.path import exists, expanduser, isdir, join, normpath

if typing.TYPE_CHECKING:
    from collections.abc import Generator, Iterable


__all__ = [
    'WIN32',
    'LINUX',
    'DARWIN',
    'POSIX',
    'find_exe',
    'find_path',
    'ensure_app_cache_dir',
    'ensure_app_config_dir',
    'ensure_app_data_dir',
    'get_app_cache_dir',
    'get_app_config_dir',
    'get_app_data_dir',
    'platform_cache_dir',
    'platform_config_dir',
    'platform_data_dir',
]

# References:
# https://stackoverflow.com/questions/446209/possible-values-from-sys-platform
WIN32: bool = sys.platform == 'win32'
LINUX: bool = sys.platform.startswith('linux')
FREEBSD: bool = sys.platform.startswith('freebsd')
DARWIN: bool = sys.platform == 'darwin'
POSIX: bool = 'posix' in sys.builtin_module_names


def platform_data_dir() -> str:
    """
    Returns path for user-specific data files

    Returns:
        str : path to the data dir used by the current operating system
    """
    if POSIX:  # nocover
        dpath_ = os.environ.get('XDG_DATA_HOME', '~/.local/share')
    elif DARWIN:  # nocover
        dpath_ = '~/Library/Application Support'
    elif WIN32:  # nocover
        dpath_ = os.environ.get('APPDATA', '~/AppData/Roaming')
    else:  # nocover
        raise NotImplementedError('Unknown Platform  %r' % (sys.platform,))
    dpath = normpath(expanduser(dpath_))
    return dpath


def platform_config_dir() -> str:
    """
    Returns a directory which should be writable for any application
    This should be used for persistent configuration files.

    Returns:
        str : path to the cache dir used by the current operating system
    """
    if POSIX:  # nocover
        dpath_ = os.environ.get('XDG_CONFIG_HOME', '~/.config')
    elif DARWIN:  # nocover
        dpath_ = '~/Library/Application Support'
    elif WIN32:  # nocover
        dpath_ = os.environ.get('APPDATA', '~/AppData/Roaming')
    else:  # nocover
        raise NotImplementedError('Unknown Platform  %r' % (sys.platform,))
    dpath = normpath(expanduser(dpath_))
    return dpath


def platform_cache_dir() -> str:
    """
    Returns a directory which should be writable for any application
    This should be used for temporary deletable data.

    Returns:
        str : path to the cache dir used by the current operating system
    """
    if POSIX:  # nocover
        dpath_ = os.environ.get('XDG_CACHE_HOME', '~/.cache')
    elif DARWIN:  # nocover
        dpath_ = '~/Library/Caches'
    elif WIN32:  # nocover
        dpath_ = os.environ.get('LOCALAPPDATA', '~/AppData/Local')
    else:  # nocover
        raise NotImplementedError('Unknown Platform  %r' % (sys.platform,))
    dpath = normpath(expanduser(dpath_))
    return dpath


# ---


def get_app_data_dir(appname: str, *args: str) -> str:
    r"""
    Returns a writable directory for an application.
    This should be used for temporary deletable data.

    Note:
        New applications should prefer :func:`ubelt.util_path.Path.appdir` i.e.
        ``ubelt.Path.appdir(appname, *args, type='data')``.

    Args:
        appname (str): the name of the application
        *args: any other subdirectories may be specified

    Returns:
        str : dpath - writable data directory for this application

    SeeAlso:
        :func:`ensure_app_data_dir`
    """
    from ubelt.util_deprecate import schedule_deprecation

    schedule_deprecation(
        modname='ubelt',
        name='get_app_data_dir and ensure_app_data_dir',
        type='function',
        migration='use ubelt.Path.appdir(type="data") instead',
        deprecate='1.2.0',
        error='2.0.0',
        remove='2.1.0',
    )
    dpath = join(platform_data_dir(), appname, *args)
    return dpath


def ensure_app_data_dir(appname: str, *args: str) -> str:
    """
    Calls :func:`get_app_data_dir` but ensures the directory exists.

    Note:
        New applications should prefer :func:`ubelt.util_path.Path.appdir` i.e.
        ``ubelt.Path.appdir(appname, *args, type='data').ensuredir()``.

    Args:
        appname (str): the name of the application
        *args: any other subdirectories may be specified

    Returns:
        str: the path to the ensured directory

    SeeAlso:
        :func:`get_app_data_dir`

    Example:
        >>> import ubelt as ub
        >>> dpath = ub.ensure_app_data_dir('ubelt')
        >>> assert exists(dpath)
    """
    from ubelt import util_path

    dpath = get_app_data_dir(appname, *args)
    util_path.ensuredir(dpath)
    return dpath


def get_app_config_dir(appname: str, *args: str) -> str:
    r"""
    Returns a writable directory for an application
    This should be used for persistent configuration files.

    Note:
        New applications should prefer :func:`ubelt.util_path.Path.appdir` i.e.
        ``ubelt.Path.appdir(appname, *args, type='config')``.

    Args:
        appname (str): the name of the application
        *args: any other subdirectories may be specified

    Returns:
        str : dpath - writable config directory for this application

    SeeAlso:
        :func:`ensure_app_config_dir`
    """
    from ubelt.util_deprecate import schedule_deprecation

    schedule_deprecation(
        modname='ubelt',
        name='get_app_config_dir and ensure_app_config_dir',
        type='function',
        migration='use ubelt.Path.appdir(type="config") instead',
        deprecate='1.2.0',
        error='2.0.0',
        remove='2.1.0',
    )
    dpath = join(platform_config_dir(), appname, *args)
    return dpath


def ensure_app_config_dir(appname: str, *args: str) -> str:
    """
    Calls :func:`get_app_config_dir` but ensures the directory exists.

    Note:
        New applications should prefer :func:`ubelt.util_path.Path.appdir` i.e.
        ``ubelt.Path.appdir(appname, *args, type='config').ensuredir()``.

    Args:
        appname (str): the name of the application
        *args: any other subdirectories may be specified

    Returns:
        str: the path to the ensured directory

    SeeAlso:
        :func:`get_app_config_dir`

    Example:
        >>> import ubelt as ub
        >>> dpath = ub.ensure_app_config_dir('ubelt')
        >>> assert exists(dpath)
    """
    from ubelt import util_path

    dpath = get_app_config_dir(appname, *args)
    util_path.ensuredir(dpath)
    return dpath


def get_app_cache_dir(appname: str, *args: str) -> str:
    r"""
    Returns a writable directory for an application.
    This should be used for temporary deletable data.

    Note:
        New applications should prefer :func:`ubelt.util_path.Path.appdir` i.e.
        ``ubelt.Path.appdir(appname, *args, type='cache')``.

    Args:
        appname (str): the name of the application
        *args: any other subdirectories may be specified

    Returns:
        str: the path to the ensured directory

    Returns:
        str : dpath - writable cache directory for this application

    SeeAlso:
        :func:`ensure_app_cache_dir`
    """
    from ubelt.util_deprecate import schedule_deprecation

    schedule_deprecation(
        modname='ubelt',
        name='get_app_cache_dir and ensure_app_cache_dir',
        type='function',
        migration='use ubelt.Path.appdir(type="cache") instead',
        deprecate='1.2.0',
        error='2.0.0',
        remove='2.1.0',
    )
    dpath = join(platform_cache_dir(), appname, *args)
    return dpath


def ensure_app_cache_dir(appname: str, *args: str) -> str:
    """
    Calls :func:`get_app_cache_dir` but ensures the directory exists.

    Note:
        New applications should prefer :func:`ubelt.util_path.Path.appdir` i.e.
        ``ubelt.Path.appdir(appname, *args, type='cache').ensuredir()``.

    Args:
        appname (str): the name of the application
        *args: any other subdirectories may be specified

    Returns:
        str: the path to the ensured directory

    SeeAlso:
        :func:`get_app_cache_dir`

    Example:
        >>> import ubelt as ub
        >>> dpath = ub.ensure_app_cache_dir('ubelt')
        >>> assert exists(dpath)
    """
    from ubelt import util_path

    dpath = get_app_cache_dir(appname, *args)
    util_path.ensuredir(dpath)
    return dpath


def find_exe(
    name: str | os.PathLike,
    multi: bool = False,
    path: str | Iterable[str | os.PathLike] | None = None,
) -> str | list[str] | None:
    """
    Locate a command.

    Search your local filesystem for an executable and return the first
    matching file with executable permission.

    Args:
        name (str | PathLike): globstr of matching filename

        multi (bool):
            if True return all matches instead of just the first.
            Defaults to False.

        path (str | Iterable[str | PathLike] | None):
            If specified, overrides the system PATH variable.

    Returns:
        str | List[str] | None: returns matching executable(s).

    SeeAlso:
        :func:`shutil.which` - which is available in Python 3.3+.

    Note:
        This is essentially the ``which`` UNIX command

    References:
        .. [SO_377017] https://stackoverflow.com/questions/377017/test-if-executable-exists-in-python/377028#377028
        .. [shutil_which] https://docs.python.org/dev/library/shutil.html#shutil.which

    Example:
        >>> # The following are programs commonly exposed via the PATH variable.
        >>> # Exact results may differ between machines.
        >>> # xdoctest: +IGNORE_WANT
        >>> import ubelt as ub
        >>> print(ub.find_exe('ls'))
        >>> print(ub.find_exe('ping'))
        >>> print(ub.find_exe('which'))
        >>> print(ub.find_exe('which', multi=True))
        >>> print(ub.find_exe('ping', multi=True))
        >>> print(ub.find_exe('noexist', multi=True))
        /usr/bin/ls
        /usr/bin/ping
        /usr/bin/which
        ['/usr/bin/which', '/bin/which']
        ['/usr/bin/ping', '/bin/ping']
        []

    Example:
        >>> import ubelt as ub
        >>> assert not ub.find_exe('!noexist', multi=False)
        >>> assert ub.find_exe('ping', multi=False) or ub.find_exe('ls', multi=False)
        >>> assert not ub.find_exe('!noexist', multi=True)
        >>> assert ub.find_exe('ping', multi=True) or ub.find_exe('ls', multi=True)

    Benchmark:
        >>> # xdoctest: +IGNORE_WANT
        >>> import ubelt as ub
        >>> import shutil
        >>> from timerit import Timerit
        >>> for timer in Timerit(1000, bestof=10, label='ub.find_exe'):
        >>>     ub.find_exe('which')
        >>> for timer in Timerit(1000, bestof=10, label='shutil.which'):
        >>>     shutil.which('which')
        Timed best=25.339 µs, mean=25.809 ± 0.3 µs for ub.find_exe
        Timed best=28.600 µs, mean=28.986 ± 0.3 µs for shutil.which
    """
    candidates = find_path(name, path=path, exact=True)
    mode = os.X_OK | os.F_OK
    results = (
        fpath
        for fpath in candidates
        if os.access(fpath, mode) and not isdir(fpath)
    )
    if not multi:
        for fpath in results:
            return fpath
        return None
    else:
        return list(results)


def find_path(
    name: str | os.PathLike,
    path: str | Iterable[str | os.PathLike] | None = None,
    exact: bool = False,
) -> Generator[str, None, None]:
    """
    Search for a file or directory on your local filesystem by name
    (file must be in a directory specified in a PATH environment variable)

    Args:
        name (str | PathLike): file name to match.
            If exact is False this may be a glob pattern

        path (str | Iterable[str | PathLike] | None):
            list of directories to search either specified as an ``os.pathsep``
            separated string or a list of directories.  Defaults to environment
            PATH.

        exact (bool): if True, only returns exact matches. Defaults to False.

    Yields:
        str: candidate - a path that matches ``name``

    Note:
        Running with ``name=''`` (i.e. ``ub.find_path('')``) will simply yield all
        directories in your PATH.

    Note:
        For recursive behavior set ``path=(d for d, _, _ in os.walk('.'))``,
        where ``'.'`` might be replaced by the root directory of interest.

    Example:
        >>> # xdoctest: +IGNORE_WANT
        >>> import ubelt as ub
        >>> print(list(ub.find_path('ping', exact=True)))
        >>> print(list(ub.find_path('bin')))
        >>> print(list(ub.find_path('gcc*')))
        >>> print(list(ub.find_path('cmake*')))
        ['/usr/bin/ping', '/bin/ping']
        []
        [... '/usr/bin/gcc-11', '/usr/bin/gcc-ranlib', ...]
        [... '/usr/bin/cmake-gui', '/usr/bin/cmake', ...]

    Example:
        >>> import ubelt as ub
        >>> from os.path import dirname
        >>> path = dirname(dirname(ub.util_platform.__file__))
        >>> res = sorted(ub.find_path('ubelt/util_*.py', path=path))
        >>> assert len(res) >= 10
        >>> res = sorted(ub.find_path('ubelt/util_platform.py', path=path, exact=True))
        >>> print(res)
        >>> assert len(res) == 1
    """
    if path is None:
        path = os.environ.get('PATH', os.defpath)
    if isinstance(path, str):
        dpaths: list[str] = path.split(os.pathsep)
    else:
        dpaths = typing.cast(typing.List[str], list(path))
    candidates: Iterable[str] = (join(dpath, name) for dpath in dpaths)
    if exact:
        if WIN32:  # nocover
            # on WIN32 allow ``name`` to omit the extension suffix by trying
            # to match with all possible "valid" suffixes specified by PATHEXT
            pathext = [''] + os.environ.get('PATHEXT', '').split(os.pathsep)
            candidates = (p + ext for p in candidates for ext in pathext)
        candidates = typing.cast(
            typing.Iterable[str], filter(exists, candidates)
        )
    else:
        import glob

        candidates = typing.cast(
            typing.Iterable[str],
            it.chain.from_iterable(
                glob.glob(pattern) for pattern in candidates
            ),
        )

    for candidate in candidates:
        yield candidate
