ubelt.util_path module¶
Functions for working with filesystem paths.
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.
The Path
object is an extension of pathlib.Path
that contains
extra convenience methods corresponding to the extra functional methods in this
module.
- class ubelt.util_path.Path(*args, **kwargs)[source]¶
Bases:
PosixPath
An extension of
pathlib.Path
with extra convenience methodsNote
- New methods are:
augment
ensuredir
expand
expandvars
ls
shrinkuser
walk
- New classmethods are:
appdir
- Modified methods are:
touch
Example
>>> # Ubelt extends pathlib functionality >>> import ubelt as ub >>> dpath = ub.Path('~/.cache/ubelt/demo_path').expand().ensuredir() >>> fpath = dpath / 'text_file.txt' >>> aug_fpath = fpath.augment(suffix='.aux', ext='.jpg').touch() >>> aug_dpath = dpath.augment('demo_path2') >>> assert aug_fpath.read_text() == '' >>> fpath.write_text('text data') >>> assert aug_fpath.exists() >>> 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
- classmethod appdir(appname, *args, type='cache')[source]¶
Returns an operating system appropriate writable directory for an application to be used for cache, configs, or data.
- Parameters
appname (str) – the name of the application
*args[str] – optional subdirs
type (str) – can be ‘cache’, ‘config’, or ‘data’.
- Returns
a new path object
- Return type
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')
- augment(suffix='', prefix='', ext=None, stem=None, dpath=None, tail='', relative=None, multidot=False)[source]¶
Create a new path with a different extension, basename, directory, prefix, and/or suffix.
See
augpath()
for more details.- Parameters
suffix (str) – Text placed between the stem and extension. Default to ‘’.
prefix (str) – Text placed in front of the stem. Defaults to ‘’.
ext (str | None) – If specified, replaces the extension
stem (str | None) – If specified, replaces the stem (i.e. basename without extension). Note: named base in
augpath()
.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 to the extension.
relative (str | PathLike | None) – Replaces
relative
withdpath
inpath
. Has no effect ifdpath
is not specified. Defaults to the dirname of the inputpath
. 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
Example
>>> import ubelt as ub >>> path = ub.Path('foo.bar') >>> suffix = '_suff' >>> prefix = 'pref_' >>> ext = '.baz' >>> newpath = path.augment(suffix, prefix, ext=ext, stem='bar') >>> print('newpath = {!r}'.format(newpath)) newpath = Path('pref_bar_suff.baz')
- delete()[source]¶
Removes a file or recursively removes a directory. If a path does not exist, then this is does nothing.
- SeeAlso:
- Returns
reference to self
- Return type
Example
>>> import ubelt as ub >>> from os.path import join >>> base = ub.Path(ub.ensure_app_cache_dir('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)
- Returns
returns itself
- Return type
Example
>>> import ubelt as ub >>> cache_dpath = ub.ensure_app_cache_dir('ubelt') >>> dpath = ub.Path(join(cache_dpath, 'ensuredir')) >>> if dpath.exists(): ... os.rmdir(dpath) >>> assert not dpath.exists() >>> dpath.ensuredir() >>> assert dpath.exists() >>> dpath.rmdir()
- 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
Example
>>> import ubelt as ub >>> #home_v1 = ub.Path('$HOME').expand() >>> home_v2 = ub.Path('~/').expand() >>> assert isinstance(home_v2, ub.Path) >>> home_v3 = ub.Path.home() >>> #print('home_v1 = {!r}'.format(home_v1)) >>> print('home_v2 = {!r}'.format(home_v2)) >>> print('home_v3 = {!r}'.format(home_v3)) >>> assert home_v3 == home_v2 # == home_v1
- 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
References
- ls()[source]¶
A convenience function to list all paths in a directory.
This is simply a wraper 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 should be used instead.
- Returns
List[Path]
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'), ]
- shrinkuser(home='~')[source]¶
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
path - shortened path replacing the home directory with a symbol
- Return type
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()) == '.'
- 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
Notes
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]) – 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’, str, str] – the root, file names, and directory 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
- class ubelt.util_path.TempDir[source]¶
Bases:
object
Context for creating and cleaning up temporary directories.
Note
This class will be DEPRECATED. The exact deprecation version and mitigation plan has not yet been developed.
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.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)
- 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
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
.dpath (str | PathLike | None) – if specified, replaces the specified “relative” directory, which by default is the parent directory.
relative (str | PathLike | None) – Replaces
relative
withdpath
inpath
. Has no effect ifdpath
is not specified. Defaults to the dirname of the inputpath
. 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
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
path - shortened path replacing the home directory with a symbol
- Return type
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 not specified, the current user is inferred.
- Returns
userhome_dpath - path to the specified home directory
- Return type
- Raises
Example
>>> from ubelt.util_path import * # NOQA >>> import getpass >>> username = getpass.getuser() >>> assert userhome() == expanduser('~') >>> assert userhome(username) == expanduser('~')
- 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]) – dir to ensure. Can also be a tuple to send to join
mode (int) – octal mode of directory
verbose (int) – verbosity
recreate (bool) – if True removes the directory and all of its contents and creates a fresh new directory. USE CAREFULLY.
- Returns
path - the ensured directory
- Return type
- SeeAlso:
Note
This function is not thread-safe in Python2
Example
>>> from ubelt.util_path import * # NOQA >>> import ubelt as ub >>> cache_dpath = ub.ensure_app_cache_dir('ubelt') >>> dpath = join(cache_dpath, 'ensuredir') >>> if exists(dpath): ... os.rmdir(dpath) >>> assert not exists(dpath) >>> ub.ensuredir(dpath) >>> assert exists(dpath) >>> os.rmdir(dpath)
- 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
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'