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: pathlib.PosixPath

An extension of pathlib.Path with extra convenience methods

Note

New methods are:
  • augment

  • ensuredir

  • expand

  • expandvars

  • shrinkuser

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
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

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.

ensuredir(mode=511)[source]

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

Returns

returns itself

Return type

Path

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()
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

CPythonIssue21301

https://bugs.python.org/issue21301

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('$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
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

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()) == '.'
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 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

Path

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:

ubelt.delete()

Returns

reference to self

Return type

Path

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

Path

Example

>>> 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())

# TODO: fix “want” string on the mac ~/.cache/ubelt ~/.config/ubelt ~/.local/share/ubelt

>>> import pytest
>>> with pytest.raises(KeyError):
>>>     ub.Path.appdir('ubelt', type='other')
class ubelt.util_path.TempDir[source]

Bases: object

Context for creating and cleaning up temporary directories.

DEPRECATE

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

path - 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 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

>>> 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

str

SeeAlso:

ubelt.Path.ensuredir()

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

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'