Source code for ubelt.util_links

r"""
Cross-platform logic for dealing with symlinks. Basic functionality should work
on all operating systems including everyone's favorite pathological OS (note
that there is an additional helper file for this case), but there are some
corner cases depending on your version. Recent versions of Windows tend to
work, but there certain system settings that cause issues. Any POSIX system
works without difficulty.

Example:
    >>> import ubelt as ub
    >>> from os.path import normpath, join
    >>> dpath = ub.Path.appdir('ubelt', normpath('demo/symlink')).ensuredir()
    >>> real_path = dpath / 'real_file.txt'
    >>> link_path = dpath / 'link_file.txt'
    >>> ub.touch(real_path)
    >>> result = ub.symlink(real_path, link_path, overwrite=True, verbose=3)
    >>> parts = result.split(os.path.sep)
    >>> print(parts[-1])
    link_file.txt
"""
from os.path import exists, islink, join, normpath
import os
import sys
import warnings
from ubelt import util_io
from ubelt import util_platform

__all__ = ['symlink']

if sys.platform.startswith('win32'):  # nocover
    from ubelt import _win32_links
else:
    _win32_links = None






def _readlink(link):
    # Note:
    # https://docs.python.org/3/library/os.html#os.readlink
    # os.readlink was changed on win32 in version 3.8: Added support for
    # directory junctions, and changed to return the substitution path (which
    # typically includes \\?\ prefix) rather than the optional “print name”
    # field that was previously returned.

    if _win32_links:  # nocover
        if _win32_links._win32_is_junction(link):
            return _win32_links._win32_read_junction(link)
    try:
        path = os.readlink(link)
        if util_platform.WIN32:  # nocover
            junction_prefix = '\\\\?\\'
            if path.startswith(junction_prefix):
                path = path[len(junction_prefix):]
        return path
    except Exception:  # nocover
        # On modern operating systems, we should never get here. (I think)
        if exists(link):
            warnings.warn('Reading symlinks seems to not be supported')
        raise


def _can_symlink(verbose=0):  # nocover
    """
    Return true if we have permission to create real symlinks.
    This check always returns True on non-win32 systems.
    If this check returns false, then we still may be able to use junctions.

    Example:
        >>> # Script
        >>> print(_can_symlink(verbose=1))
    """
    if _win32_links is not None:
        return _win32_links._win32_can_symlink(verbose)
    else:
        return True


def _dirstats(dpath=None):  # nocover
    """
    Testing helper for printing directory information
    (mostly for investigating windows weirdness)

    The column prefixes stand for:
    (E - exists), (L - islink), (F - isfile), (D - isdir), (J - isjunction)
    """
    from ubelt import util_colors
    if dpath is None:
        dpath = os.getcwd()
    print('+--------------')
    print('Listing for dpath={}'.format(dpath))
    print('E L F D J - path')
    print('+--------------')
    if not os.path.exists(dpath):
        print('... does not exist')
    else:
        paths = sorted(os.listdir(dpath))
        for path in paths:
            full_path = join(dpath, path)
            E = os.path.exists(full_path)
            L = os.path.islink(full_path)
            F = os.path.isfile(full_path)
            D = os.path.isdir(full_path)
            J = util_platform.WIN32 and _win32_links._win32_is_junction(full_path)
            ELFDJ = [E, L, F, D, J]
            if   ELFDJ == [1, 0, 0, 1, 0]:
                # A directory
                path = util_colors.color_text(path, 'green')
            elif ELFDJ == [1, 0, 1, 0, 0]:
                # A file (or a hard link, they're indistinguishable with 1 query)
                path = util_colors.color_text(path, 'white')
            elif ELFDJ == [1, 0, 0, 1, 1]:
                # A directory junction
                path = util_colors.color_text(path, 'yellow')
            elif ELFDJ == [1, 1, 1, 0, 0]:
                # A file link
                path = util_colors.color_text(path, 'brightgreen')
            elif ELFDJ == [1, 1, 0, 1, 0]:
                # A directory link
                path = util_colors.color_text(path, 'brightcyan')
            elif ELFDJ == [0, 1, 0, 0, 0]:
                # A broken file link
                path = util_colors.color_text(path, 'red')
            elif ELFDJ == [0, 1, 0, 1, 0]:
                # A broken directory link
                path = util_colors.color_text(path, 'darkred')
            elif ELFDJ == [0, 0, 0, 1, 1]:
                # A broken directory junction
                path = util_colors.color_text(path, 'purple')
            elif ELFDJ == [1, 0, 1, 0, 1]:
                # A file junction? That's not good.
                # I guess this is a windows 7 thing?
                path = util_colors.color_text(path, 'red')
            elif ELFDJ == [1, 1, 0, 0, 0]:
                # Windows? Why? What does this mean!?
                # A directory link that can't be resolved?
                path = util_colors.color_text(path, 'red')
            elif ELFDJ == [0, 0, 0, 0, 0]:
                # Windows? AGAIN? HOW DO YOU LIST FILES THAT DONT EXIST?
                # I get it, they are probably broken junctions, but common
                # That should probably be 00011 not 00000
                path = util_colors.color_text(path, 'red')
            else:
                print('dpath = {!r}'.format(dpath))
                print('path = {!r}'.format(path))
                raise AssertionError(str(ELFDJ) + str(path))
            line = '{E:d} {L:d} {F:d} {D:d} {J:d} - {path}'.format(**locals())
            if os.path.islink(full_path):
                line += ' -> ' + os.readlink(full_path)
            elif _win32_links is not None:
                if _win32_links._win32_is_junction(full_path):
                    resolved = _win32_links._win32_read_junction(full_path)
                    line += ' => ' + resolved
            print(line)
    print('+--------------')