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 |
-
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
- 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
- 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: 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
- 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 commandReferences
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 or str) – file name to match. If exact is False this may be a glob pattern
- path (str or Iterable[str | 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, 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