Attempt to create a symbolic link.

    TODO:
        Can this be fixed on windows?

    Args:
        path (str): path to real file or directory
        link_path (str): path to desired location for symlink
        overwrite (bool): overwrite existing symlinks (default = False)
        on_error (str): strategy for dealing with errors.
            raise or ignore
        verbose (int):  verbosity level (default=2)

    Returns:
        str: link path

    CommandLine:
        python -m utool.util_path symlink

    Example:
        >>> # ENABLE_DOCTEST
        >>> from utool.util_path import *  # NOQA
        >>> import utool as ut
        >>> dpath = ut.get_app_resource_dir('utool')
        >>> real_path = join(dpath, 'real_file.txt')
        >>> link_path = join(dpath, 'link_file.txt')
        >>> ut.emap(ut.delete, [real_path, link_path], verbose=0)
        >>> ut.writeto(real_path, 'foo')
        >>> result = symlink(real_path, link_path)
        >>> assert ut.readfrom(result) == 'foo'
        >>> ut.emap(ut.delete, [real_path, link_path], verbose=0)

    Example:
        >>> # ENABLE_DOCTEST
        >>> from utool.util_path import *  # NOQA
        >>> import utool as ut
        >>> real_dpath = ut.get_app_resource_dir('utool', 'real_dpath')
        >>> link_dpath = ut.augpath(real_dpath, newfname='link_dpath')
        >>> real_path = join(real_dpath, 'afile.txt')
        >>> link_path = join(link_dpath, 'afile.txt')
        >>> ut.emap(ut.delete, [real_path, link_path], verbose=0)
        >>> ut.ensuredir(real_dpath)
        >>> ut.writeto(real_path, 'foo')
        >>> result = symlink(real_dpath, link_dpath)
        >>> assert ut.readfrom(link_path) == 'foo'
        >>> ut.delete(link_dpath, verbose=0)
        >>> assert ut.checkpath(real_path)
        >>> ut.delete(real_dpath, verbose=0)
        >>> assert not ut.checkpath(real_path)

def symlink(real_path, link_path, overwrite=False, on_error='raise',
            verbose=2):
    """
    Attempt to create a symbolic link.

    TODO:
        Can this be fixed on windows?

    Args:
        path (str): path to real file or directory
        link_path (str): path to desired location for symlink
        overwrite (bool): overwrite existing symlinks (default = False)
        on_error (str): strategy for dealing with errors.
            raise or ignore
        verbose (int):  verbosity level (default=2)

    Returns:
        str: link path

    CommandLine:
        python -m utool.util_path symlink

    Example:
        >>> # ENABLE_DOCTEST
        >>> from utool.util_path import *  # NOQA
        >>> import utool as ut
        >>> dpath = ut.get_app_resource_dir('utool')
        >>> real_path = join(dpath, 'real_file.txt')
        >>> link_path = join(dpath, 'link_file.txt')
        >>> ut.emap(ut.delete, [real_path, link_path], verbose=0)
        >>> ut.writeto(real_path, 'foo')
        >>> result = symlink(real_path, link_path)
        >>> assert ut.readfrom(result) == 'foo'
        >>> ut.emap(ut.delete, [real_path, link_path], verbose=0)

    Example:
        >>> # ENABLE_DOCTEST
        >>> from utool.util_path import *  # NOQA
        >>> import utool as ut
        >>> real_dpath = ut.get_app_resource_dir('utool', 'real_dpath')
        >>> link_dpath = ut.augpath(real_dpath, newfname='link_dpath')
        >>> real_path = join(real_dpath, 'afile.txt')
        >>> link_path = join(link_dpath, 'afile.txt')
        >>> ut.emap(ut.delete, [real_path, link_path], verbose=0)
        >>> ut.ensuredir(real_dpath)
        >>> ut.writeto(real_path, 'foo')
        >>> result = symlink(real_dpath, link_dpath)
        >>> assert ut.readfrom(link_path) == 'foo'
        >>> ut.delete(link_dpath, verbose=0)
        >>> assert ut.checkpath(real_path)
        >>> ut.delete(real_dpath, verbose=0)
        >>> assert not ut.checkpath(real_path)
    """
    path = normpath(real_path)
    link = normpath(link_path)
    if verbose:
        print('[util_path] Creating symlink: path={} link={}'.format(path, link))
    if os.path.islink(link):
        if verbose:
            print('[util_path] symlink already exists')
        os_readlink = getattr(os, "readlink", None)
        if callable(os_readlink):
            if os_readlink(link) == path:
                if verbose > 1:
                    print('[path] ... and points to the right place')
                return link
        else:
            print('[util_path] Warning, symlinks are not implemented on windows')
        if verbose > 1:
            print('[util_path] ... but it points somewhere else')
        if overwrite:
            delete(link, verbose > 1)
        elif on_error == 'ignore':
            return False
    try:
        os_symlink = getattr(os, "symlink", None)
        if callable(os_symlink):
            os_symlink(path, link)
        else:
            win_shortcut(path, link)
    except Exception as ex:
        import utool as ut
        checkpath(link, verbose=True)
        checkpath(path, verbose=True)
        do_raise = (on_error == 'raise')
        ut.printex(ex, '[util_path] error making symlink',
                   iswarning=not do_raise)
        if do_raise:
            raise
    return link