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.
- class ubelt.util_path.TempDir[source]¶
Bases:
object
Context for creating and cleaning up temporary directories.
Example
>>> with TempDir() as self: >>> dpath = self.dpath >>> assert exists(dpath) >>> assert not exists(dpath)
Example
>>> self = TempDir() >>> dpath = self.ensure() >>> assert exists(dpath) >>> self.cleanup() >>> assert not exists(dpath)
- ubelt.util_path.augpath(path, suffix='', prefix='', ext=None, 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, default=’’) – placed between the basename and extension
prefix (str, default=’’) – placed in front of the basename
ext (str, default=None) – if specified, replaces the extension
base (str, default=None) – if specified, replaces the basename without extension
dpath (str | PathLike, default=None) – if specified, replaces the specified “relative” directory, which by default is the parent directory.
relative (str | PathLike, default=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, default=False) – 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
>>> 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
- ubelt.util_path.shrinkuser(path, home='~')[source]¶
Inverse of
os.path.expanduser()
.- Parameters
path (str | PathLike) – path in system file structure
home (str, default=’~’) – 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 tilde
- Return type
str
Example
>>> 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, default=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
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 getpass >>> username = getpass.getuser() >>> assert userhome() == expanduser('~') >>> assert userhome(username) == expanduser('~')
- ubelt.util_path.ensuredir(dpath, mode=1023, verbose=None, 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, default=0o1777) – octal mode of directory
verbose (int, default=0) – verbosity
recreate (bool, default=False) – 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
str
Notes
This function is not thread-safe in Python2
Example
>>> from ubelt.util_platform 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.
Less aggressive than truepath. Only expands environs and tilde. Does not change relative paths to absolute paths.
- Parameters
path (str | PathLike) – string representation of a path
- Returns
expanded path
- Return type
str
Example
>>> import ubelt as ub >>> assert normpath(ub.expandpath('~/foo')) == join(ub.userhome(), 'foo') >>> assert ub.expandpath('foo') == 'foo'