# ubelt.util_path module

Path and filesystem utilities.

The `Path` object is an extension of `pathlib.Path` that contains extra convenience methods corresponding to the extra functional methods in this module. (New in 0.11.0). See the class documentation for more details.

This module also defines functional path-related utilities, but moving forward users should prefer using `Path` over standalone functional methods. The functions methods will still be available for the forseable future, but their functionality is made redundant by `Path`. For completeness these functions are listed

The `expandpath()` function expands the tilde to `$HOME` and environment variables to their values.

The `augpath()` function creates variants of an existing path without having to spend multiple lines of code splitting it up and stitching it back together.

The `shrinkuser()` function replaces your home directory with a tilde.

The `userhome()` function reports the home directory of the current user of the operating system.

The `ensuredir()` function operates like `mkdir -p` in unix.

Note

In the future the part of this module that defines Path may be renamed to util_pathlib.

class ubelt.util_path.Path(*args, **kwargs)

  Bases: `PosixPath`

  This class extends `pathlib.Path` with extra functionality and convenience methods.

  New methods are designed to support chaining.

  In addition to new methods this class supports the addition (`+`) operator via which allows for better drop-in compatibility with code using existing string-based paths.

  Note

  On windows this inherits from `pathlib.WindowsPath`.

  New methods are

  > - `ubelt.Path.ensuredir()` - Like mkdir but with easier defaults.

  > - `ubelt.Path.delete()` - Previously pathlib could only remove one file at a time.

  > - `ubelt.Path.copy()` - Pathlib has no similar functionality.

  > - `ubelt.Path.move()` - Pathlib has no similar functionality.

  > - `ubelt.Path.augment()` - Unifies and extends disparate functionality across pathlib.

  > - `ubelt.Path.expand()` - Unifies existing environ and home expansion.

  > - `ubelt.Path.ls()` - Like iterdir, but more interactive.

  > - `ubelt.Path.shrinkuser()` - Python has no similar functionality.

  > - `ubelt.Path.walk()` - Pathlib had no similar functionality.

  New classmethods are

  > - `ubelt.Path.appdir()` - application directories

  Modified methods are

  > - `ubelt.Path.touch()` - returns self to support chaining

  > - `ubelt.Path.chmod()` - returns self to support chaining and

  >     now accepts string-based permission codes.

  Example

      >>> # Ubelt extends pathlib functionality
      >>> import ubelt as ub
      >>> # Chain expansion and mkdir with cumbersome args.
      >>> dpath = ub.Path('~/.cache/ubelt/demo_path').expand().ensuredir()
      >>> fpath = dpath / 'text_file.txt'
      >>> # Augment is concise and chainable
      >>> aug_fpath = fpath.augment(stemsuffix='.aux', ext='.jpg').touch()
      >>> aug_dpath = dpath.augment(stemsuffix='demo_path2')
      >>> assert aug_fpath.read_text() == ''
      >>> fpath.write_text('text data')
      >>> assert aug_fpath.exists()
      >>> # Delete is akin to "rm -rf" and is also chainable.
      >>> assert not aug_fpath.delete().exists()
      >>> assert dpath.exists()
      >>> assert not dpath.delete().exists()
      >>> print(f'{str(fpath.shrinkuser()).replace(os.path.sep, "/")}')
      >>> print(f'{str(dpath.shrinkuser()).replace(os.path.sep, "/")}')
      >>> print(f'{str(aug_fpath.shrinkuser()).replace(os.path.sep, "/")}')
      >>> print(f'{str(aug_dpath.shrinkuser()).replace(os.path.sep, "/")}')
      ~/.cache/ubelt/demo_path/text_file.txt
      ~/.cache/ubelt/demo_path
      ~/.cache/ubelt/demo_path/text_file.aux.jpg
      ~/.cache/ubelt/demo_pathdemo_path2

  Inherited unmodified properties from `pathlib.Path` are:

  > - `pathlib.PurePath.anchor`

  > - `pathlib.PurePath.name`

  > - `pathlib.PurePath.parts`

  > - `pathlib.PurePath.parent`

  > - `pathlib.PurePath.parents`

  > - `pathlib.PurePath.suffix`

  > - `pathlib.PurePath.suffixes`

  > - `pathlib.PurePath.stem`

  > - `pathlib.PurePath.drive`

  > - `pathlib.PurePath.root`

  Inherited unmodified classmethods from `pathlib.Path` are:

  > - `pathlib.Path.cwd()`

  > - `pathlib.Path.home()`

  Inherited unmodified methods from `pathlib.Path` are:

  > - `pathlib.Path.samefile()`

  > - `pathlib.Path.iterdir()`

  > - `pathlib.Path.glob()`

  > - `pathlib.Path.rglob()`

  > - `pathlib.Path.resolve()`

  > - `pathlib.Path.lstat()`

  > - `pathlib.Path.stat()`

  > - `pathlib.Path.owner()`

  > - `pathlib.Path.group()`

  > - `pathlib.Path.open()`

  > - `pathlib.Path.read_bytes()`

  > - `pathlib.Path.read_text()`

  > - `pathlib.Path.write_bytes()`

  > - `pathlib.Path.write_text()`

  > - `pathlib.Path.readlink()`

  > - `pathlib.Path.mkdir()` - we recommend `ubelt.Path.ensuredir()` instead.

  > - `pathlib.Path.lchmod()`

  > - `pathlib.Path.unlink()`

  > - `pathlib.Path.rmdir()`

  > - `pathlib.Path.rename()`

  > - `pathlib.Path.replace()`

  > - `pathlib.Path.symlink_to()`

  > - `pathlib.Path.hardlink_to()`

  > - `pathlib.Path.link_to()` - deprecated

  > - `pathlib.Path.exists()`

  > - `pathlib.Path.is_dir()`

  > - `pathlib.Path.is_file()`

  > - `pathlib.Path.is_mount()`

  > - `pathlib.Path.is_symlink()`

  > - `pathlib.Path.is_block_device()`

  > - `pathlib.Path.is_char_device()`

  > - `pathlib.Path.is_fifo()`

  > - `pathlib.Path.is_socket()`

  > - `pathlib.Path.expanduser()` - we recommend `ubelt.Path.expand()` instead.

  > - `pathlib.PurePath.as_posix()`

  > - `pathlib.PurePath.as_uri()`

  > - `pathlib.PurePath.with_name()` - we recommend `ubelt.Path.augment()` instead.

  > - `pathlib.PurePath.with_stem()` - we recommend `ubelt.Path.augment()` instead.

  > - `pathlib.PurePath.with_suffix()` - we recommend `ubelt.Path.augment()` instead.

  > - `pathlib.PurePath.relative_to()`

  > - `pathlib.PurePath.joinpath()`

  > - `pathlib.PurePath.is_relative_to()`

  > - `pathlib.PurePath.is_absolute()`

  > - `pathlib.PurePath.is_reserved()`

  > - `pathlib.PurePath.match()`

  classmethod appdir(appname=None, *args, type='cache')

    Returns a standard platform specific directory for an application to use as cache, config, or data.

    The default root location depends on the platform and is specified the the following table:

    TextArt

               | POSIX            | Windows        | MacOSX
        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

    Parameters:

      - appname (str | None) – The name of the application.

      - *args – optional subdirs

      - type (str) – the type of data the expected to be stored in this application directory. Valid options are ‘cache’, ‘config’, or ‘data’.

    Returns:

      a new path object for the specified application directory.

    Return type:

      Path

    SeeAlso:

      This provides functionality similar to the appdirs - and platformdirs - packages.

    Example

        >>> # xdoctest: +IGNORE_WANT
        >>> import ubelt as ub
        >>> print(ub.Path.appdir('ubelt', type='cache').shrinkuser())
        >>> print(ub.Path.appdir('ubelt', type='config').shrinkuser())
        >>> print(ub.Path.appdir('ubelt', type='data').shrinkuser())
        ~/.cache/ubelt
        ~/.config/ubelt
        ~/.local/share/ubelt
        >>> import pytest
        >>> with pytest.raises(KeyError):
        >>>     ub.Path.appdir('ubelt', type='other')

    Example

        >>> # xdoctest: +IGNORE_WANT
        >>> import ubelt as ub
        >>> # Can now call appdir without any arguments
        >>> print(ub.Path.appdir().shrinkuser())
        ~/.cache

  augment(prefix='', stemsuffix='', ext=None, stem=None, dpath=None, tail='', relative=None, multidot=False, suffix='')

    Create a new path with a different extension, basename, directory, prefix, and/or suffix.

    A prefix is inserted before the basename. A stemsuffix is inserted between the basename and the extension. The tail is placed at the very end of the path. The basename and extension can be replaced with a new one. Essentially a path is broken down into components (dpath, stem, ext), and then recombined as (dpath, prefix, stem, stemsuffix, ext, tail) after replacing any specified component.

    Parameters:

      - prefix (str) – Text placed in front of the stem. Defaults to ‘’.

      - stemsuffix (str) – Text placed between the stem and extension. Defaults to ‘’.

      - ext (str | None) – If specified, replaces the extension

      - stem (str | None) – If specified, replaces the stem (i.e. basename without extension).

      - dpath (str | PathLike | None) – If specified, replaces the specified “relative” directory, which by default is the parent directory.

      - tail (str | None) – If specified, appends this text the very end of the path - after the extension.

      - relative (str | PathLike | None) – Replaces `relative` with `dpath` in `path`. Has no effect if `dpath` is not specified. Defaults to the dirname of the input `path`. experimental not currently implemented.

      - multidot (bool) – Allows extensions to contain multiple dots. Specifically, if False, everything after the last dot in the basename is the extension. If True, everything after the first dot in the basename is the extension.

    SeeAlso:

      - `ubelt.augpath()`

      - `pathlib.PurePath.with_stem()`

      - `pathlib.PurePath.with_name()`

      - `pathlib.PurePath.with_suffix()`

    Returns:

      augmented path

    Return type:

      Path

    Warning

    NOTICE OF BACKWARDS INCOMPATIBILITY.

    THE INITIAL RELEASE OF Path.augment suffered from an unfortunate variable naming decision that conflicts with pathlib.Path

        p = ub.Path('the.entire.fname.or.dname.is.the.name.exe')
        print(f'p     ={p}')
        print(f'p.name={p.name}')
        p = ub.Path('the.stem.ends.here.ext')
        print(f'p     ={p}')
        print(f'p.stem={p.stem}')
        p = ub.Path('only.the.last.dot.is.the.suffix')
        print(f'p       ={p}')
        print(f'p.suffix={p.suffix}')
        p = ub.Path('but.all.suffixes.can.be.recovered')
        print(f'p         ={p}')
        print(f'p.suffixes={p.suffixes}')

    Example

        >>> import ubelt as ub
        >>> path = ub.Path('foo.bar')
        >>> suffix = '_suff'
        >>> prefix = 'pref_'
        >>> ext = '.baz'
        >>> newpath = path.augment(prefix=prefix, stemsuffix=suffix, ext=ext, stem='bar')
        >>> print('newpath = {!r}'.format(newpath))
        newpath = Path('pref_bar_suff.baz')

    Example

        >>> import ubelt as ub
        >>> path = ub.Path('foo.bar')
        >>> stemsuffix = '_suff'
        >>> prefix = 'pref_'
        >>> ext = '.baz'
        >>> newpath = path.augment(prefix=prefix, stemsuffix=stemsuffix, ext=ext, stem='bar')
        >>> print('newpath = {!r}'.format(newpath))

    Example

        >>> # Compare our augpath(ext=...) versus pathlib with_suffix(...)
        >>> import ubelt as ub
        >>> cases = [
        >>>     ub.Path('no_ext'),
        >>>     ub.Path('one.ext'),
        >>>     ub.Path('double..dot'),
        >>>     ub.Path('two.many.cooks'),
        >>>     ub.Path('path.with.three.dots'),
        >>>     ub.Path('traildot.'),
        >>>     ub.Path('doubletraildot..'),
        >>>     ub.Path('.prefdot'),
        >>>     ub.Path('..doubleprefdot'),
        >>> ]
        >>> for path in cases:
        >>>     print('--')
        >>>     print('path = {}'.format(ub.repr2(path, nl=1)))
        >>>     ext = '.EXT'
        >>>     method_pathlib = path.with_suffix(ext)
        >>>     method_augment = path.augment(ext=ext)
        >>>     if method_pathlib == method_augment:
        >>>         print(ub.color_text('sagree', 'green'))
        >>>     else:
        >>>         print(ub.color_text('disagree', 'red'))
        >>>     print('path.with_suffix({}) = {}'.format(ext, ub.repr2(method_pathlib, nl=1)))
        >>>     print('path.augment(ext={}) = {}'.format(ext, ub.repr2(method_augment, nl=1)))
        >>>     print('--')

  delete()

    Removes a file or recursively removes a directory. If a path does not exist, then this is does nothing.

    SeeAlso:

      `ubelt.delete()`

    Returns:

      reference to self

    Return type:

      Path

    Example

        >>> import ubelt as ub
        >>> from os.path import join
        >>> base = ub.Path.appdir('ubelt', 'delete_test2')
        >>> dpath1 = (base / 'dir').ensuredir()
        >>> (base / 'dir' / 'subdir').ensuredir()
        >>> (base / 'dir' / 'to_remove1.txt').touch()
        >>> fpath1 = (base / 'dir' / 'subdir' / 'to_remove3.txt').touch()
        >>> fpath2 = (base / 'dir' / 'subdir' / 'to_remove2.txt').touch()
        >>> assert all(p.exists() for p in [dpath1, fpath1, fpath2])
        >>> fpath1.delete()
        >>> assert all(p.exists() for p in [dpath1, fpath2])
        >>> assert not fpath1.exists()
        >>> dpath1.delete()
        >>> assert not any(p.exists() for p in [dpath1, fpath1, fpath2])

  ensuredir(mode=511)

    Concise alias of `self.mkdir(parents=True, exist_ok=True)`

    Parameters:

      mode (int) – octal permissions if a new directory is created. Defaults to 0o777.

    Returns:

      returns itself

    Return type:

      Path

    Example

        >>> import ubelt as ub
        >>> cache_dpath = ub.Path.appdir('ubelt').ensuredir()
        >>> dpath = ub.Path(cache_dpath, 'newdir')
        >>> dpath.delete()
        >>> assert not dpath.exists()
        >>> dpath.ensuredir()
        >>> assert dpath.exists()
        >>> dpath.rmdir()

  mkdir(mode=511, parents=False, exist_ok=False)

    Create a new directory at this given path.

    Note

    The ubelt extension is the same as the original pathlib method, except this returns returns the path instead of None.

    Parameters:

      - mode (int) – permission bits

      - parents (bool) – create parents

      - exist_ok (bool) – fail if exists

    Returns:

      returns itself

    Return type:

      Path

  expand()

    Expands user tilde and environment variables.

    Concise alias of `Path(os.path.expandvars(self.expanduser()))`

    Returns:

      path with expanded environment variables and tildes

    Return type:

      Path

    Example

        >>> import ubelt as ub
        >>> home_v1 = ub.Path('~/').expand()
        >>> home_v2 = ub.Path.home()
        >>> print('home_v1 = {!r}'.format(home_v1))
        >>> print('home_v2 = {!r}'.format(home_v2))
        >>> assert home_v1 == home_v2

  expandvars()

    As discussed in [CPythonIssue21301], CPython won’t be adding expandvars to pathlib. I think this is a mistake, so I added it in this extension.

    Returns:

      path with expanded environment variables

    Return type:

      Path

    References

    [CPythonIssue21301]

    https://bugs.python.org/issue21301

  ls(pattern=None)

    A convenience function to list all paths in a directory.

    This is a wrapper around iterdir that returns the results as a list instead of a generator. This is mainly for faster navigation in IPython. In production code `iterdir` or `glob` should be used instead.

    Parameters:

      pattern (None | str) – if specified, performs a glob instead of an iterdir.

    Returns:

      an eagerly evaluated list of paths

    Return type:

      List[‘Path’]

    Note

    When pattern is specified only paths matching the pattern are returned, not the paths inside matched directories. This is different than bash semantics where the pattern is first expanded and then ls is performed on all matching paths.

    Example

        >>> import ubelt as ub
        >>> self = ub.Path.appdir('ubelt/tests/ls')
        >>> (self / 'dir1').ensuredir()
        >>> (self / 'dir2').ensuredir()
        >>> (self / 'file1').touch()
        >>> (self / 'file2').touch()
        >>> (self / 'dir1/file3').touch()
        >>> (self / 'dir2/file4').touch()
        >>> children = self.ls()
        >>> assert isinstance(children, list)
        >>> print(ub.repr2(sorted([p.relative_to(self) for p in children])))
        [
            Path('dir1'),
            Path('dir2'),
            Path('file1'),
            Path('file2'),
        ]
        >>> children = self.ls('dir*/*')
        >>> assert isinstance(children, list)
        >>> print(ub.repr2(sorted([p.relative_to(self) for p in children])))
        [
            Path('dir1/file3'),
            Path('dir2/file4'),
        ]

  shrinkuser(home='~')

    Shrinks your home directory by replacing it with a tilde.

    This is the inverse of `os.path.expanduser()`.

    Parameters:

      home (str) – symbol used to replace the home path. Defaults to ‘~’, but you might want to use ‘$HOME’ or ‘%USERPROFILE%’ instead.

    Returns:

      shortened path replacing the home directory with a symbol

    Return type:

      Path

    Example

        >>> import ubelt as ub
        >>> path = ub.Path('~').expand()
        >>> assert str(path.shrinkuser()) == '~'
        >>> assert str(ub.Path((str(path) + '1')).shrinkuser()) == str(path) + '1'
        >>> assert str((path / '1').shrinkuser()) == join('~', '1')
        >>> assert str((path / '1').shrinkuser('$HOME')) == join('$HOME', '1')
        >>> assert str(ub.Path('.').shrinkuser()) == '.'

  chmod(mode, follow_symlinks=True)

    Change the permissions of the path, like os.chmod().

    Parameters:

      - mode (int | str) – either a stat code to pass directly to `os.chmod()` or a string-based code to construct modified permissions. See note for details on the string-based chmod codes.

      - follow_symlinks (bool) – if True, and this path is a symlink, modify permission of the file it points to, otherwise if False, modify the link permission.

    Note

    From the chmod man page:

    The format of a symbolic mode is [ugoa…][[-+=][perms…]…], where perms is either zero or more letters from the set rwxXst, or a single letter from the set ugo. Multiple symbolic modes can be given, separated by commas.

    Note

    Like `os.chmod()`, this may not work on Windows or on certain filesystems.

    Returns:

      returns self for chaining

    Return type:

      Path

    Example

        >>> # xdoctest: +REQUIRES(POSIX)
        >>> import ubelt as ub
        >>> from ubelt.util_path import _encode_chmod_int
        >>> dpath = ub.Path.appdir('ubelt/tests/chmod').ensuredir()
        >>> fpath = (dpath / 'file.txt').touch()
        >>> fpath.chmod('ugo+rw,ugo-x')
        >>> print(_encode_chmod_int(fpath.stat().st_mode))
        u=rw,g=rw,o=rw
        >>> fpath.chmod('o-rwx')
        >>> print(_encode_chmod_int(fpath.stat().st_mode))
        u=rw,g=rw
        >>> fpath.chmod(0o646)
        >>> print(_encode_chmod_int(fpath.stat().st_mode))
        u=rw,g=r,o=rw

  touch(mode=438, exist_ok=True)

    Create this file with the given access mode, if it doesn’t exist.

    Returns:

      returns itself

    Return type:

      Path

    Note

    The `ubelt.util_io.touch()` function currently has a slightly different implementation. This uses whatever the pathlib version is. This may change in the future.

  relative_to(*other, **kwargs)

    Return the relative path to another path identified by the passed arguments. If the operation is not possible (because this is not a subpath of the other path), raise ValueError.

    Includes a Backport of `pathlib.Path.relative_to()` with `walk_up=True` that’s not available pre 3.12.

    Parameters:

      - other (Path | str) – the base path

      - walk_up (bool) – controls whether .. may be used to resolve the path.

    Returns:

      the new relative path

    Return type:

      Path

    References

    https://stackoverflow.com/questions/38083555/using-pathlibs-relative-to-for-directories-on-the-same-level https://github.com/p2p-ld/numpydantic/blob/66fffc49f87bfaaa2f4d05bf1730c343b10c9cc6/src/numpydantic/serialization.py#L107-L142

    Example

        >>> import ubelt as ub
        >>> import pytest
        >>> self = ub.Path('foo/bar')
        >>> other = ub.Path('foo/bar/baz')
        >>> result = self.relative_to(other, walk_up=True)
        >>> assert result == ub.Path('..')
        >>> with pytest.raises(ValueError):
        >>>     self.relative_to(other)
        >>> with pytest.raises(ValueError):
        >>>     self.relative_to(other, walk_up=False)
        >>> with pytest.raises(TypeError):
        >>>     self.relative_to(other, not_a_kwarg=False)

  walk(topdown=True, onerror=None, followlinks=False, **kwargs)

    A variant of `os.walk()` for pathlib

    Parameters:

      - topdown (bool) – if True starts yield nodes closer to the root first otherwise yield nodes closer to the leaves first.

      - onerror (Callable[[OSError], None] | None) – A function with one argument of type OSError. If the error is raised the walk is aborted, otherwise it continues.

      - followlinks (bool) – if True recurse into symbolic directory links

      - **kwargs – Accepts aliases the 3.12 version of the above names: top_down, on_error, follow_symlinks. In the future we may switch the 3.12 variants to be the primary arguments.

    Yields:

      Tuple[‘Path’, List[str], List[str]] – the root path, directory names, and file names

    Example

        >>> import ubelt as ub
        >>> self = ub.Path.appdir('ubelt/tests/ls')
        >>> (self / 'dir1').ensuredir()
        >>> (self / 'dir2').ensuredir()
        >>> (self / 'file1').touch()
        >>> (self / 'file2').touch()
        >>> (self / 'dir1/file3').touch()
        >>> (self / 'dir2/file4').touch()
        >>> subdirs = list(self.walk())
        >>> assert len(subdirs) == 3

    Example

        >>> # Modified from the stdlib
        >>> import os
        >>> from os.path import join, getsize
        >>> import email
        >>> import ubelt as ub
        >>> base = ub.Path(email.__file__).parent
        >>> for root, dirs, files in base.walk():
        >>>     print(root, " consumes", end="")
        >>>     print(sum(getsize(join(root, name)) for name in files), end="")
        >>>     print("bytes in ", len(files), " non-directory files")
        >>>     if 'CVS' in dirs:
        >>>         dirs.remove('CVS')  # don't visit CVS directories

  endswith(suffix, *args)

    Test if the fspath representation ends with `suffix`.

    Allows ubelt.Path to be a better drop-in replacement when working with string-based paths.

    Parameters:

      - suffix (str | Tuple[str, …]) – One or more suffixes to test for

      - *args – start (int): if specified begin testing at this position. end (int): if specified stop testing at this position.

    Returns:

      True if any of the suffixes match.

    Return type:

      bool

    Example

        >>> import ubelt as ub
        >>> base = ub.Path('base')
        >>> assert base.endswith('se')
        >>> assert not base.endswith('be')
        >>> # test start / stop cases
        >>> assert ub.Path('aabbccdd').endswith('cdd', 5)
        >>> assert not ub.Path('aabbccdd').endswith('cdd', 6)
        >>> assert ub.Path('aabbccdd').endswith('cdd', 5, 10)
        >>> assert not ub.Path('aabbccdd').endswith('cdd', 5, 7)
        >>> # test tuple case
        >>> assert ub.Path('aabbccdd').endswith(('foo', 'cdd'))
        >>> assert ub.Path('foo').endswith(('foo', 'cdd'))
        >>> assert not ub.Path('bar').endswith(('foo', 'cdd'))

  startswith(prefix, *args)

    Test if the fspath representation starts with `prefix`.

    Allows ubelt.Path to be a better drop-in replacement when working with string-based paths.

    Parameters:

      - prefix (str | Tuple[str, …]) – One or more prefixes to test for

      - *args – start (int): if specified begin testing at this position. end (int): if specified stop testing at this position.

    Returns:

      True if any of the prefixes match.

    Return type:

      bool

    Example

        >>> import ubelt as ub
        >>> base = ub.Path('base')
        >>> assert base.startswith('base')
        >>> assert not base.startswith('all your')
        >>> # test start / stop cases
        >>> assert ub.Path('aabbccdd').startswith('aab', 0)
        >>> assert ub.Path('aabbccdd').startswith('aab', 0, 5)
        >>> assert not ub.Path('aabbccdd').startswith('aab', 1, 5)
        >>> assert not ub.Path('aabbccdd').startswith('aab', 0, 2)
        >>> # test tuple case
        >>> assert ub.Path('aabbccdd').startswith(('foo', 'aab'))
        >>> assert ub.Path('foo').startswith(('foo', 'aab'))
        >>> assert not ub.Path('bar').startswith(('foo', 'aab'))

  _request_copy_function(follow_file_symlinks=True, follow_dir_symlinks=True, meta='stats')

    Get a copy_function based on specified capabilities

  copy(dst, follow_file_symlinks=False, follow_dir_symlinks=False, meta='stats', overwrite=False)

    Copy this file or directory to dst.

    By default files are never overwritten and symlinks are copied as-is.

    At a basic level (i.e. ignoring symlinks) for each path argument (`src` and `dst`) these can either be files, directories, or not exist. Given these three states, the following table summarizes how this function copies this path to its destination.

    TextArt

        +----------+------------------------+------------------------+----------+
        | dst      | dir                    | file                   | no-exist |
        +----------+                        |                        |          |
        | src      |                        |                        |          |
        +==========+========================+========================+==========+
        | dir      | error-or-overwrite-dst | error                  | dst      |
        +----------+------------------------+------------------------+----------+
        | file     | dst / src.name         | error-or-overwrite-dst | dst      |
        +----------+------------------------+------------------------+----------+
        | no-exist | error                  | error                  | error    |
        +----------+------------------------+------------------------+----------+

    In general, the contents of src will be the contents of dst, except for the one case where a file is copied into an existing directory. In this case the name is used to construct a fully qualified destination.

    Parameters:

      - dst (str | PathLike) – if `src` is a file and `dst` does not exist, copies this to `dst` if `src` is a file and `dst` is a directory, copies this to `dst / src.name`

        if `src` is a directory and `dst` does not exist, copies this to `dst` if `src` is a directory and `dst` is a directory, errors unless overwrite is True, in which case, copies this to `dst` and overwrites anything conflicting path.

      - follow_file_symlinks (bool) – If True and src is a link, the link will be resolved before it is copied (i.e. the data is duplicated), otherwise just the link itself will be copied.

      - follow_dir_symlinks (bool) – if True when src is a directory and contains symlinks to other directories, the contents of the linked data are copied, otherwise when False only the link itself is copied.

      - meta (str | None) – Indicates what metadata bits to copy. This can be ‘stats’ which tries to copy all metadata (i.e. like `shutil.copy2()`), ‘mode’ which copies just the permission bits (i.e. like `shutil.copy()`), or None, which ignores all metadata (i.e. like `shutil.copyfile()`).

      - overwrite (bool) – if False, and target file exists, this will raise an error, otherwise the file will be overwritten.

    Returns:

      where the path was copied to

    Return type:

      Path

    Note

    This is implemented with a combination of `shutil.copy()`, `shutil.copy2()`, and `shutil.copytree()`, but the defaults and behavior here are different (and ideally safer and more intuitive).

    Note

    Unlike cp on Linux, copying a src directory into a dst directory will not implicitly add the src directory name to the dst directory. This means we cannot copy directory `<parent>/<dname>` to `<dst>` and expect the result to be `<dst>/<dname>`.

    Conceptually you can expect `<parent>/<dname>/<contents>` to exist in `<dst>/<contents>`.

    Example

        >>> import ubelt as ub
        >>> root = ub.Path.appdir('ubelt', 'tests', 'path', 'copy').delete().ensuredir()
        >>> paths = {}
        >>> dpath = (root / 'orig').ensuredir()
        >>> clone0 = (root / 'dst_is_explicit').ensuredir()
        >>> clone1 = (root / 'dst_is_parent').ensuredir()
        >>> paths['fpath'] = (dpath / 'file0.txt').touch()
        >>> paths['empty_dpath'] = (dpath / 'empty_dpath').ensuredir()
        >>> paths['nested_dpath'] = (dpath / 'nested_dpath').ensuredir()
        >>> (dpath / 'nested_dpath/d0').ensuredir()
        >>> (dpath / 'nested_dpath/d0/f1.txt').touch()
        >>> (dpath / 'nested_dpath/d0/f2.txt').touch()
        >>> print('paths = {}'.format(ub.repr2(paths, nl=1)))
        >>> assert all(p.exists() for p in paths.values())
        >>> paths['fpath'].copy(clone0 / 'file0.txt')
        >>> paths['fpath'].copy(clone1)
        >>> paths['empty_dpath'].copy(clone0 / 'empty_dpath')
        >>> paths['empty_dpath'].copy((clone1 / 'empty_dpath_alt').ensuredir(), overwrite=True)
        >>> paths['nested_dpath'].copy(clone0 / 'nested_dpath')
        >>> paths['nested_dpath'].copy((clone1 / 'nested_dpath_alt').ensuredir(), overwrite=True)

  move(dst, follow_file_symlinks=False, follow_dir_symlinks=False, meta='stats')

    Move a file from one location to another, or recursively move a directory from one location to another.

    This method will refuse to overwrite anything, and there is currently no overwrite option for technical reasons. This may change in the future.

    Parameters:

      - dst (str | PathLike) – A non-existing path where this file will be moved.

      - follow_file_symlinks (bool) – If True and src is a link, the link will be resolved before it is copied (i.e. the data is duplicated), otherwise just the link itself will be copied.

      - follow_dir_symlinks (bool) – if True when src is a directory and contains symlinks to other directories, the contents of the linked data are copied, otherwise when False only the link itself is copied.

      - meta (str | None) – Indicates what metadata bits to copy. This can be ‘stats’ which tries to copy all metadata (i.e. like shutil.copy2), ‘mode’ which copies just the permission bits (i.e. like shutil.copy), or None, which ignores all metadata (i.e. like shutil.copyfile).

    Note

    This method will refuse to overwrite anything.

    This is implemented via `shutil.move()`, which depends heavily on `os.rename()` semantics. For this reason, this function will error if it would overwrite any data. If you want an overwriting variant of move we recommend you either either copy the data, and then delete the original (potentially inefficient), or use `shutil.move()` directly if you know how `os.rename()` works on your system.

    Returns:

      where the path was moved to

    Return type:

      Path

    Example

        >>> import ubelt as ub
        >>> dpath = ub.Path.appdir('ubelt', 'tests', 'path', 'move').delete().ensuredir()
        >>> paths = {}
        >>> paths['dpath0'] = (dpath / 'dpath0').ensuredir()
        >>> paths['dpath00'] = (dpath / 'dpath0' / 'sub0').ensuredir()
        >>> paths['fpath000'] = (dpath / 'dpath0' / 'sub0' / 'f0.txt').touch()
        >>> paths['fpath001'] = (dpath / 'dpath0' / 'sub0' / 'f1.txt').touch()
        >>> paths['dpath01'] = (dpath / 'dpath0' / 'sub1').ensuredir()
        >>> print('paths = {}'.format(ub.repr2(paths, nl=1)))
        >>> assert all(p.exists() for p in paths.values())
        >>> paths['dpath0'].move(dpath / 'dpath1')

class ubelt.util_path.TempDir

  Bases: `object`

  Context for creating and cleaning up temporary directories.

  Warning

  DEPRECATED. Use `tempfile` instead.

  Note

  This exists because `tempfile.TemporaryDirectory` was introduced in Python 3.2. Thus once ubelt no longer supports python 2.7, this class will be deprecated.

  Variables:

    dpath (str | None) – the temporary path

  Note

  # WE MAY WANT TO KEEP THIS FOR WINDOWS.

  Example

      >>> from ubelt.util_path import *  # NOQA
      >>> with TempDir() as self:
      >>>     dpath = self.dpath
      >>>     assert exists(dpath)
      >>> assert not exists(dpath)

  Example

      >>> from ubelt.util_path import *  # NOQA
      >>> self = TempDir()
      >>> dpath = self.ensure()
      >>> assert exists(dpath)
      >>> self.cleanup()
      >>> assert not exists(dpath)

  ensure()
    Returns:

      the path

    Return type:

      str

  cleanup()
  start()
    Returns:

      self

    Return type:

      TempDir

ubelt.util_path.augpath(path, suffix='', prefix='', ext=None, tail='', base=None, dpath=None, relative=None, multidot=False)

  Create a new path with a different extension, basename, directory, prefix, and/or suffix.

  A prefix is inserted before the basename. A suffix is inserted between the basename and the extension. The basename and extension can be replaced with a new one. Essentially a path is broken down into components (dpath, base, ext), and then recombined as (dpath, prefix, base, suffix, ext) after replacing any specified component.

  Parameters:

    - path (str | PathLike) – a path to augment

    - suffix (str) – placed between the basename and extension Note: this is referred to as stemsuffix in `ub.Path.augment()`.

    - prefix (str) – placed in front of the basename

    - ext (str | None) – if specified, replaces the extension

    - tail (str | None) – If specified, appends this text to the extension

    - base (str | None) – if specified, replaces the basename without extension. Note: this is referred to as stem in `ub.Path.augment()`.

    - dpath (str | PathLike | None) – if specified, replaces the specified “relative” directory, which by default is the parent directory.

    - relative (str | PathLike | None) – Replaces `relative` with `dpath` in `path`. Has no effect if `dpath` is not specified. Defaults to the dirname of the input `path`. experimental not currently implemented.

    - multidot (bool) – Allows extensions to contain multiple dots. Specifically, if False, everything after the last dot in the basename is the extension. If True, everything after the first dot in the basename is the extension.

  Returns:

    augmented path

  Return type:

    str

  SeeAlso:

    `ubelt.Path.augment()`

  Example

      >>> import ubelt as ub
      >>> path = 'foo.bar'
      >>> suffix = '_suff'
      >>> prefix = 'pref_'
      >>> ext = '.baz'
      >>> newpath = ub.augpath(path, suffix, prefix, ext=ext, base='bar')
      >>> print('newpath = %s' % (newpath,))
      newpath = pref_bar_suff.baz

  Example

      >>> from ubelt.util_path import *  # NOQA
      >>> augpath('foo.bar')
      'foo.bar'
      >>> augpath('foo.bar', ext='.BAZ')
      'foo.BAZ'
      >>> augpath('foo.bar', suffix='_')
      'foo_.bar'
      >>> augpath('foo.bar', prefix='_')
      '_foo.bar'
      >>> augpath('foo.bar', base='baz')
      'baz.bar'
      >>> augpath('foo.tar.gz', ext='.zip', multidot=True)
      foo.zip
      >>> augpath('foo.tar.gz', ext='.zip', multidot=False)
      foo.tar.zip
      >>> augpath('foo.tar.gz', suffix='_new', multidot=True)
      foo_new.tar.gz
      >>> augpath('foo.tar.gz', suffix='_new', tail='.cache', multidot=True)
      foo_new.tar.gz.cache

ubelt.util_path.shrinkuser(path, home='~')

  Inverse of `os.path.expanduser()`.

  Parameters:

    - path (str | PathLike) – path in system file structure

    - home (str) – symbol used to replace the home path. Defaults to `'~'`, but you might want to use `'$HOME'` or `'%USERPROFILE%'` instead.

  Returns:

    shortened path replacing the home directory with a symbol

  Return type:

    str

  SeeAlso:

    `ubelt.Path.shrinkuser()`

  Example

      >>> from ubelt.util_path import *  # NOQA
      >>> path = expanduser('~')
      >>> assert path != '~'
      >>> assert shrinkuser(path) == '~'
      >>> assert shrinkuser(path + '1') == path + '1'
      >>> assert shrinkuser(path + '/1') == join('~', '1')
      >>> assert shrinkuser(path + '/1', '$HOME') == join('$HOME', '1')
      >>> assert shrinkuser('.') == '.'

ubelt.util_path.userhome(username=None)

  Returns the path to some user’s home directory.

  Parameters:

    username (str | None) – name of a user on the system. If unspecified, the current user is inferred from standard environment variables.

  Returns:

    path to the specified home directory

  Return type:

    str

  Raises:

    - KeyError – if the specified user does not exist on the system

    - OSError – if username is unspecified and the current user cannot be inferred

  Example

      >>> import ubelt as ub
      >>> import os
      >>> import getpass
      >>> username = getpass.getuser()
      >>> userhome_target = os.path.expanduser('~')
      >>> userhome_got1 = ub.userhome()
      >>> userhome_got2 = ub.userhome(username)
      >>> print(f'username={username}')
      >>> print(f'userhome_got1={userhome_got1}')
      >>> print(f'userhome_got2={userhome_got2}')
      >>> print(f'userhome_target={userhome_target}')
      >>> assert userhome_got1 == userhome_target
      >>> assert userhome_got2 == userhome_target

ubelt.util_path.ensuredir(dpath, mode=1023, verbose=0, recreate=False)

  Ensures that directory will exist. Creates new dir with sticky bits by default

  Parameters:

    - dpath (str | PathLike | Tuple[str | PathLike]) – directory to create if it does not exist.

    - mode (int) – octal permissions if a new directory is created. Defaults to 0o1777.

    - verbose (int) – verbosity

    - recreate (bool) – if True removes the directory and all of its contents and creates a new empty directory. DEPRECATED: Use `ub.Path(dpath).delete().ensuredir()` instead.

  Returns:

    the ensured directory

  Return type:

    str

  SeeAlso:

    `ubelt.Path.ensuredir()`

  Example

      >>> import ubelt as ub
      >>> dpath = ub.Path.appdir('ubelt', 'ensuredir')
      >>> dpath.delete()
      >>> assert not dpath.exists()
      >>> ub.ensuredir(dpath)
      >>> assert dpath.exists()
      >>> dpath.delete()

ubelt.util_path.expandpath(path)

  Shell-like environment variable and tilde path expansion.

  Parameters:

    path (str | PathLike) – string representation of a path

  Returns:

    expanded path

  Return type:

    str

  SeeAlso:

    `ubelt.Path.expand()`

  Example

      >>> from ubelt.util_path import *  # NOQA
      >>> import ubelt as ub
      >>> assert normpath(ub.expandpath('~/foo')) == join(ub.userhome(), 'foo')
      >>> assert ub.expandpath('foo') == 'foo'

class ubelt.util_path.ChDir(dpath)

  Bases: `object`

  Context manager that changes the current working directory and then returns you to where you were.

  This is nearly the same as the stdlib `contextlib.chdir()`, with the exception that it will do nothing if the input path is None (i.e. the user did not want to change directories).

  SeeAlso:

    `contextlib.chdir()`

  Example

      >>> import ubelt as ub
      >>> dpath = ub.Path.appdir('ubelt/tests/chdir').ensuredir()
      >>> dir1 = (dpath / 'dir1').ensuredir()
      >>> dir2 = (dpath / 'dir2').ensuredir()
      >>> with ChDir(dpath):
      >>>     assert ub.Path.cwd() == dpath
      >>>     # change to the given directory, and then returns back
      >>>     with ChDir(dir1):
      >>>         assert ub.Path.cwd() == dir1
      >>>         with ChDir(dir2):
      >>>             assert ub.Path.cwd() == dir2
      >>>             # changes inside the context manager will be reset
      >>>             os.chdir(dpath)
      >>>         assert ub.Path.cwd() == dir1
      >>>     assert ub.Path.cwd() == dpath
      >>>     with ChDir(dir1):
      >>>         assert ub.Path.cwd() == dir1
      >>>         with ChDir(None):
      >>>             assert ub.Path.cwd() == dir1
      >>>             # When disabled, the cwd does *not* reset at context exit
      >>>             os.chdir(dir2)
      >>>         assert ub.Path.cwd() == dir2
      >>>         os.chdir(dir1)
      >>>         # Dont change dirs, but reset to your cwd at context end
      >>>         with ChDir('.'):
      >>>             os.chdir(dir2)
      >>>         assert ub.Path.cwd() == dir1
      >>>     assert ub.Path.cwd() == dpath

  Parameters:

    dpath (str | PathLike | None) – The new directory to work in. If None, then the context manager is disabled.