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)[source]

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

New classmethods are

Modified methods are

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:

Inherited unmodified methods from pathlib.Path are:

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

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='')[source]

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

See augpath() for more details.

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:

pathlib.Path.with_stem() pathlib.Path.with_name() pathlib.Path.with_suffix()

Returns:

augmented path

Return type:

Path

Warning

NOTICE OF BACKWARDS INCOMPATABILITY.

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()[source]

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)[source]

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)[source]

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()[source]

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()[source]

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

ls(pattern=None)[source]

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='~')[source]

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)[source]

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)[source]

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.

walk(topdown=True, onerror=None, followlinks=False)[source]

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

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)[source]

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)[source]

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')[source]

Get a copy_function based on specified capabilities

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

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')[source]

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[source]

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()[source]
Returns:

the path

Return type:

str

cleanup()[source]
start()[source]
Returns:

self

Return type:

TempDir

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

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

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='~')[source]

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

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)[source]

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)[source]

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)[source]

Shell-like environment variable and tilde path expansion.

Parameters:

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

Returns:

expanded path

Return type:

str

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)[source]

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.