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
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
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.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:pathlib.Path.mkdir()
- we recommendubelt.Path.ensuredir()
instead.pathlib.Path.link_to()
- deprecatedpathlib.Path.expanduser()
- we recommendubelt.Path.expand()
instead.pathlib.PurePath.with_name()
- we recommendubelt.Path.augment()
instead.pathlib.PurePath.with_stem()
- we recommendubelt.Path.augment()
instead.pathlib.PurePath.with_suffix()
- we recommendubelt.Path.augment()
instead.
- 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
- 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. Default to ‘’. Note: this is just called suffix in
ub.augpath()
.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 the very end of the path - after 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.
- SeeAlso:
pathlib.Path.with_stem()
pathlib.Path.with_name()
pathlib.Path.with_suffix()
- Returns
augmented path
- Return type
Note
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}’)
p.name p.stem p.suffixes p.parts
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:
- Returns
reference to self
- Return type
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)
- Returns
returns itself
- Return type
Example
>>> import ubelt as ub >>> cache_dpath = ub.Path.appdir('ubelt').ensuredir() >>> dpath = ub.Path(join(cache_dpath, 'ensuredir')) >>> if dpath.exists(): ... os.rmdir(dpath) >>> 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 variant is the same, except it returns the path as well.
- Parameters
mode (int) – perms
parents (bool) – create parents
exist_ok (bool) – fail if exists
- Returns
returns itself
- Return type
- 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(pattern=None)[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
orglob
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 dir 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
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
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 endswith a particular string
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 are matched.
- Return type
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 startswith a particular string
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 are matched.
- Return type
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'))
- 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
anddst
) 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. likeshutil.copy()
), or None, which ignores all metadata (i.e. likeshutil.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 actually copied to
- Return type
Note
This is implemented with a combination of
shutil.copy()
,shutil.copy2()
, andshutil.copytree()
, but the The defaults and behavior here are noticably different (and hopefully safer and more intuitive).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 onos.rename()
semantics. For this reason, this function 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 useshutil.move()
directly if you know howos.rename()
works on your system.- Returns
where the path was actually moved to
- Return type
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()) >>> # xdev.tree_repr(dpath, max_files=10) >>> paths['dpath0'].move(dpath / 'dpath1') >>> # xdev.tree_repr(dpath, max_files=10)
- 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 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
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 ubelt as ub >>> import getpass >>> username = getpass.getuser() >>> userhome_target = 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]) – 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.Path.appdir('ubelt').ensuredir() >>> 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'