ubelt.util_platform module

The goal of this module is to provide an idomatic cross-platform pattern of accessing platform dependant file systems.

Standard application directory structure: cache, config, and other XDG standards [1].

Notes

Table mapping the type of directory to the system default environment variable. Inspired by [2,3,4].

Linux | Win32 | Darwin

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

References

..[1] https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html ..[2] https://stackoverflow.com/questions/43853548/xdg-windows ..[3] https://stackoverflow.com/questions/11113974/cross-plat-path ..[4] https://github.com/harawata/appdirs#supported-directories

ubelt.util_platform.platform_data_dir()[source]

Returns path for user-specific data files

Returns:path to the data dir used by the current operating system
Return type:PathLike
ubelt.util_platform.platform_config_dir()[source]

Returns a directory which should be writable for any application This should be used for persistent configuration files.

Returns:path to the cahce dir used by the current operating system
Return type:PathLike
ubelt.util_platform.platform_cache_dir()[source]

Returns a directory which should be writable for any application This should be used for temporary deletable data.

Returns:path to the cache dir used by the current operating system
Return type:PathLike
ubelt.util_platform.get_app_data_dir(appname, *args)[source]

Returns a writable directory for an application. This should be used for temporary deletable data.

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
Returns:

dpath: writable data directory for this application

Return type:

PathLike

SeeAlso:
ensure_app_data_dir
ubelt.util_platform.ensure_app_data_dir(appname, *args)[source]

Calls get_app_data_dir but ensures the directory exists.

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
SeeAlso:
get_app_data_dir

Example

>>> import ubelt as ub
>>> dpath = ub.ensure_app_data_dir('ubelt')
>>> assert exists(dpath)
ubelt.util_platform.get_app_config_dir(appname, *args)[source]

Returns a writable directory for an application This should be used for persistent configuration files.

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
Returns:

dpath: writable config directory for this application

Return type:

PathLike

SeeAlso:
ensure_app_config_dir
ubelt.util_platform.ensure_app_config_dir(appname, *args)[source]

Calls get_app_config_dir but ensures the directory exists.

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
SeeAlso:
get_app_config_dir

Example

>>> import ubelt as ub
>>> dpath = ub.ensure_app_config_dir('ubelt')
>>> assert exists(dpath)
ubelt.util_platform.get_app_cache_dir(appname, *args)[source]

Returns a writable directory for an application. This should be used for temporary deletable data.

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
Returns:

dpath: writable cache directory for this application

Return type:

PathLike

SeeAlso:
ensure_app_cache_dir
ubelt.util_platform.ensure_app_cache_dir(appname, *args)[source]

Calls get_app_cache_dir but ensures the directory exists.

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
SeeAlso:
get_app_cache_dir

Example

>>> import ubelt as ub
>>> dpath = ub.ensure_app_cache_dir('ubelt')
>>> assert exists(dpath)
ubelt.util_platform.startfile(fpath, verbose=True)[source]

Uses default program defined by the system to open a file. This is done via os.startfile on windows, open on mac, and xdg-open on linux.

Parameters:
  • fpath (PathLike) – a file to open using the program associated with the files extension type.
  • verbose (int) – verbosity

References

http://stackoverflow.com/questions/2692873/quote-posix

DisableExample:
>>> # This test interacts with a GUI frontend, not sure how to test.
>>> import ubelt as ub
>>> base = ub.ensure_app_cache_dir('ubelt')
>>> fpath1 = join(base, 'test_open.txt')
>>> ub.touch(fpath1)
>>> proc = ub.startfile(fpath1)
ubelt.util_platform.find_exe(name, multi=False, path=None)[source]

Locate a command.

Search your local filesystem for an executable and return the first matching file with executable permission.

Parameters:
  • name (str) – globstr of matching filename
  • multi (bool) – if True return all matches instead of just the first. Defaults to False.
  • path (str or Iterable[PathLike]) – overrides the system PATH variable.
Returns:

returns matching executable(s).

Return type:

PathLike or List[PathLike] or None

SeeAlso:
shutil.which - which is available in Python 3.3+.

Notes

This is essentially the which UNIX command

References

https://stackoverflow.com/questions/377017/test-if-executable-exists-in-python/377028#377028 https://docs.python.org/dev/library/shutil.html#shutil.which

Example

>>> find_exe('ls')
>>> find_exe('ping')
>>> assert find_exe('which') == find_exe(find_exe('which'))
>>> find_exe('which', multi=True)
>>> find_exe('ping', multi=True)
>>> find_exe('cmake', multi=True)
>>> find_exe('nvcc', multi=True)
>>> find_exe('noexist', multi=True)

Example

>>> assert not find_exe('noexist', multi=False)
>>> assert find_exe('ping', multi=False)
>>> assert not find_exe('noexist', multi=True)
>>> assert find_exe('ping', multi=True)
Benchmark:
>>> # xdoctest: +IGNORE_WANT
>>> import ubelt as ub
>>> import shutil
>>> for timer in ub.Timerit(100, bestof=10, label='ub.find_exe'):
>>>     ub.find_exe('which')
>>> for timer in ub.Timerit(100, bestof=10, label='shutil.which'):
>>>     shutil.which('which')
Timed best=58.71 µs, mean=59.64 ± 0.96 µs for ub.find_exe
Timed best=72.75 µs, mean=73.07 ± 0.22 µs for shutil.which
ubelt.util_platform.find_path(name, path=None, exact=False)[source]

Search for a file or directory on your local filesystem by name (file must be in a directory specified in a PATH environment variable)

Parameters:
  • fname (PathLike or str) – file name to match. If exact is False this may be a glob pattern
  • path (str or Iterable[PathLike]) – list of directories to search either specified as an os.pathsep separated string or a list of directories. Defaults to environment PATH.
  • exact (bool) – if True, only returns exact matches. Default False.

Notes

For recursive behavior set path=(d for d, _, _ in os.walk(‘.’)), where ‘.’ might be replaced by the root directory of interest.

Example

>>> list(find_path('ping', exact=True))
>>> list(find_path('bin'))
>>> list(find_path('bin'))
>>> list(find_path('*cc*'))
>>> list(find_path('cmake*'))

Example

>>> import ubelt as ub
>>> from os.path import dirname
>>> path = dirname(dirname(ub.util_platform.__file__))
>>> res = sorted(find_path('ubelt/util_*.py', path=path))
>>> assert len(res) >= 10
>>> res = sorted(find_path('ubelt/util_platform.py', path=path, exact=True))
>>> print(res)
>>> assert len(res) == 1
ubelt.util_platform.editfile(fpath, verbose=True)[source]

DEPRICATED: This has been ported to xdev, please use that version.

Opens a file or code corresponding to a live python object in your preferred visual editor. This function is mainly useful in an interactive IPython session.

The visual editor is determined by the VISUAL environment variable. If this is not specified it defaults to gvim.

Parameters:
  • fpath (PathLike) – a file path or python module / function
  • verbose (int) – verbosity
DisableExample:
>>> # This test interacts with a GUI frontend, not sure how to test.
>>> import ubelt as ub
>>> ub.editfile(ub.util_platform.__file__)
>>> ub.editfile(ub)
>>> ub.editfile(ub.editfile)
ubelt.util_platform.platform_resource_dir()[source]

Alias for platform_cache_dir

DEPRICATED in favor of platform_config_dir / platform_data_dir

Returns a directory which should be writable for any application This should be used for persistent configuration files.

Returns:path to the resource dir used by the current operating system
Return type:PathLike
ubelt.util_platform.get_app_resource_dir(appname, *args)[source]

Returns a writable directory for an application This should be used for persistent configuration files.

DEPRICATED in favor of get_app_config_dir / get_app_data_dir

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
Returns:

dpath: writable resource directory for this application

Return type:

PathLike

SeeAlso:
ensure_app_resource_dir
ubelt.util_platform.ensure_app_resource_dir(appname, *args)[source]

Calls get_app_resource_dir but ensures the directory exists.

DEPRICATED in favor of ensure_app_config_dir / ensure_app_data_dir

Parameters:
  • appname (str) – the name of the application
  • *args – any other subdirectories may be specified
SeeAlso:
get_app_resource_dir