# ubelt.util_links module

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 pytest
    >>> import ubelt as ub
    >>> if ub.WIN32:
    >>>     pytest.skip()  # hack for windows for now. Todo cleaner xdoctest conditional
    >>> 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

ubelt.util_links.symlink(real_path, link_path, overwrite=False, verbose=0)

  Create a link `link_path` that mirrors `real_path`.

  This function attempts to create a real symlink, but will fall back on a hard link or junction if symlinks are not supported.

  Parameters:

    - real_path (str | PathLike) – path to real file or directory

    - link_path (str | PathLike) – path to desired location for symlink

    - overwrite (bool) – overwrite existing symlinks. This will not overwrite real files on systems with proper symlinks. However, on older versions of windows junctions are indistinguishable from real files, so we cannot make this guarantee. Defaults to False.

    - verbose (int) – verbosity level. Defaults to 0.

  Returns:

    link path

  Return type:

    str | PathLike

  Note

  In the future we may rework and rename this function to something like `link`, `pathlink`, `fslink`, etc… to indicate that it may perform multiple types of links. We may also allow the user to specify which type of link (e.g. symlink, hardlink, reflink, junction) they would like to use.

  Note

  On systems that do not contain support for symlinks (e.g. some versions / configurations of Windows), this function will fall back on hard links or junctions [WikiNTFSLinks], [WikiHardLink]. The differences between the two are explained in [WikiSymLink].

  If symlinks are not available, then `link_path` and `real_path` must exist on the same filesystem. Given that, this function always works in the sense that (1) `link_path` will mirror the data from `real_path`, (2) updates to one will effect the other, and (3) no extra space will be used.

  More details can be found in `ubelt._win32_links`. On systems that support symlinks (e.g. Linux), none of the above applies.

  Note

  This function may contain a bug when creating a relative link

  References

  [WikiSymLink]

  https://en.wikipedia.org/wiki/Symbolic_link

  [WikiHardLink]

  https://en.wikipedia.org/wiki/Hard_link

  [WikiNTFSLinks]

  https://en.wikipedia.org/wiki/NTFS_links

  Example

      >>> import pytest
      >>> import ubelt as ub
      >>> if ub.WIN32:
      >>>     pytest.skip()  # hack for windows for now. Todo cleaner xdoctest conditional
      >>> import ubelt as ub
      >>> dpath = ub.Path.appdir('ubelt', 'test_symlink0').delete().ensuredir()
      >>> real_path = (dpath / 'real_file.txt')
      >>> link_path = (dpath / 'link_file.txt')
      >>> real_path.write_text('foo')
      >>> result = ub.symlink(real_path, link_path)
      >>> assert ub.Path(result).read_text() == 'foo'
      >>> dpath.delete()  # clenaup

  Example

      >>> import pytest
      >>> import ubelt as ub
      >>> if ub.WIN32:
      >>>     pytest.skip()  # hack for windows for now. Todo cleaner xdoctest conditional
      >>> import ubelt as ub
      >>> from ubelt.util_links import _dirstats
      >>> dpath = ub.Path.appdir('ubelt', 'test_symlink1').delete().ensuredir()
      >>> _dirstats(dpath)
      >>> real_dpath = (dpath / 'real_dpath').ensuredir()
      >>> link_dpath = real_dpath.augment(stem='link_dpath')
      >>> real_path = (dpath / 'afile.txt')
      >>> link_path = (dpath / 'afile.txt')
      >>> real_path.write_text('foo')
      >>> result = ub.symlink(real_dpath, link_dpath)
      >>> assert link_path.read_text() == 'foo', 'read should be same'
      >>> link_path.write_text('bar')
      >>> _dirstats(dpath)
      >>> assert link_path.read_text() == 'bar', 'very bad bar'
      >>> assert real_path.read_text() == 'bar', 'changing link did not change real'
      >>> real_path.write_text('baz')
      >>> _dirstats(dpath)
      >>> assert real_path.read_text() == 'baz', 'very bad baz'
      >>> assert link_path.read_text() == 'baz', 'changing real did not change link'
      >>> ub.delete(link_dpath, verbose=1)
      >>> _dirstats(dpath)
      >>> assert not link_dpath.exists(), 'link should not exist'
      >>> assert real_path.exists(), 'real path should exist'
      >>> _dirstats(dpath)
      >>> ub.delete(dpath, verbose=1)
      >>> _dirstats(dpath)
      >>> assert not real_path.exists()

  Example

      >>> import pytest
      >>> import ubelt as ub
      >>> if ub.WIN32:
      >>>     pytest.skip()  # hack for windows for now. Todo cleaner xdoctest conditional
      >>> # Specifying bad paths should error.
      >>> import ubelt as ub
      >>> import pytest
      >>> dpath = ub.Path.appdir('ubelt', 'test_symlink2').ensuredir()
      >>> real_path = dpath / 'real_file.txt'
      >>> link_path = dpath / 'link_file.txt'
      >>> real_path.write_text('foo')
      >>> with pytest.raises(ValueError, match='link_path .* cannot be empty'):
      >>>     ub.symlink(real_path, '')
      >>> with pytest.raises(ValueError, match='real_path .* cannot be empty'):
      >>>     ub.symlink('', link_path)