ubelt.util_platform module

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

Standard application directory structure: cache, config, and other XDG standards 1. This is similar to the more focused appdirs module 5. In the future ubelt may directly use appdirs.

Notes

Table mapping the type of directory to the system default environment variable. Inspired by 2, 3, and 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

5

https://github.com/ActiveState/appdirs

6

https://stackoverflow.com/questions/43853548/xdg-windows

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

str

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

str

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

str

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

str

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

Returns

the path to the ensured directory

Return type

str

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

str

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

Returns

the path to the ensured directory

Return type

str

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

the path to the ensured directory

Return type

str

Returns

dpath - writable cache directory for this application

Return type

str

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

Returns

the path to the ensured directory

Return type

str

SeeAlso:

get_app_cache_dir()

Example

>>> import ubelt as ub
>>> dpath = ub.ensure_app_cache_dir('ubelt')
>>> assert exists(dpath)
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 | PathLike) – globstr of matching filename

  • multi (bool, default=False) – if True return all matches instead of just the first.

  • path (str | PathLike | Iterable[str | PathLike], default=None) – overrides the system PATH variable.

Returns

returns matching executable(s).

Return type

str | List[str] | 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 (str | PathLike) – file name to match. If exact is False this may be a glob pattern

  • path (str | Iterable[str | PathLike], default=None) – list of directories to search either specified as an os.pathsep separated string or a list of directories. Defaults to environment PATH.

  • exact (bool, default=False) – if True, only returns exact matches.

Yields

str – candidate - a path that matches name

Notes

Running with name='' (i.e. ub.find_path('')) will simply yield all directories in your PATH.

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