homebase module¶
This module provides an API for determining application specific directories for data, config, logs, etc.
public module members:
user_data_dir (app_name, app_author[, …]) |
Return the full path to the user data dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t. |
user_config_dir (app_name, app_author[, …]) |
Return the full path to the user config dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t. |
user_cache_dir (app_name, app_author[, …]) |
Return the full path to the user cache dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t. |
user_state_dir (app_name, app_author[, …]) |
Return the full path to the user state dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t. |
user_logs_dir (app_name, app_author[, …]) |
Return the full path to the user log dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t. |
site_data_dir (app_name, app_author[, …]) |
Return the full path to the OS wide data dir for this application. |
site_config_dir (app_name, app_author[, …]) |
Return the full path to the OS wide config dir for this application. |
site_data_dir_list (app_name, app_author[, …]) |
Return the list of full path to the OS wide data directories for this application. |
site_config_dir_list (app_name, app_author[, …]) |
Return the list of full path to the OS wide data directories for this application. |
This code is inspired by and builds on top of code from http://github.com/ActiveState/appdirs
-
user_data_dir
(app_name, app_author, version=None, roaming=False, use_virtualenv=True, create=True)[source]¶ Return the full path to the user data dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t.
If using a virtualenv, the path returned is
/path/to/virtualenv/data/app_name
Typical user data directories are:
- Mac OS X:
~/Library/Application Support/<app_name>
- Unix:
~/.local/share/<app_name> # or $XDG_DATA_HOME/<app_name>, if defined.
- Win XP (not roaming):
C:\Documents and Settings\<username>\Application Data\<app_author>\<app_name>
- Win XP (roaming):
C:\Documents and Settings\<username>\Local Settings\Application Data\<app_author>\<app_name>
- Win 7 (not roaming):
C:\Users\<username>\AppData\Local\<app_author>\<app_name>
- Win 7 (roaming):
C:\Users\<username>\AppData\Roaming\<app_author>\<app_name>
For Unix, we follow the XDG spec and support
$XDG_DATA_HOME
. That means, by default~/.local/share/<AppName>
.Parameters: - app_name (str) – Name of the application. Will be appended to the base user data path.
- app_author (str) – Only used in Windows when not in a virtualenv, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- roaming (bool) – roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be synchronized on login. See <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx> for a discussion of issues.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the user data dir for this application.
Return type: - Mac OS X:
-
user_config_dir
(app_name, app_author, version=None, roaming=False, use_virtualenv=True, create=True)[source]¶ Return the full path to the user config dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t.
If using a virtualenv, the path returned is
/path/to/virtualenv/config/app_name
- Typical user config directories are:
- Mac OS X: same as user_data_dir
- Unix:
~/.config/<AppName> # or in $XDG_CONFIG_HOME, if defined
- Win *: same as user_data_dir
For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default
~/.config/<AppName>
.Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- roaming (bool) – roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be synchronized on login. See <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx> for a discussion of issues.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the user config dir for this application.
Return type:
-
user_cache_dir
(app_name, app_author, version=None, use_virtualenv=True, create=True)[source]¶ Return the full path to the user cache dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t.
If using a virtualenv, the path returned is
/path/to/virtualenv/cache/app_name
- Typical user cache directories are:
- Mac OS X:
~/Library/Caches/<AppName>
- Unix:
~/.cache/<AppName> (XDG default)
- Win XP:
C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Cache
- Vista:
C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Cache
- Mac OS X:
Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the user cache dir for this application.
Return type:
-
user_state_dir
(app_name, app_author, version=None, roaming=False, use_virtualenv=True, create=True)[source]¶ Return the full path to the user state dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t.
If using a virtualenv, the path returned is
/path/to/virtualenv/state/app_name
- Typical user state directories are:
- Mac OS X: same as user_data_dir
- Unix:
~/.local/state/<AppName> # or in $XDG_STATE_HOME, if defined
- Win *: same as user_data_dir
For Unix, we follow this Debian proposal https://wiki.debian.org/XDGBaseDirectorySpecification#state to extend the XDG spec and support $XDG_STATE_HOME. That means, by default
~/.local/state/<AppName>
.Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- roaming (bool) – roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be synchronized on login. See <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx> for a discussion of issues.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the user state dir for this application.
Return type:
-
user_logs_dir
(app_name, app_author, version=None, use_virtualenv=True, create=True)[source]¶ Return the full path to the user log dir for this application, using a virtualenv location as a base, if it is exists, and falling back to the host OS’s convention if it doesn’t.
If using a virtualenv, the path returned is
:bash:
/path/to/virtualenv/log/app_name``- Typical user log directories are:
- Mac OS X:
~/Library/Logs/<AppName>
- Unix:
~/.cache/<AppName>/log # or under $XDG_CACHE_HOME if defined
- Win XP:
C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Logs
- Vista:
C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Logs
- Mac OS X:
Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the user log dir for this application.
Return type:
-
site_data_dir
(app_name, app_author, version=None, use_virtualenv=True, create=False)[source]¶ Return the full path to the OS wide data dir for this application.
- Typical site data directories are:
- Mac OS X:
/Library/Application Support/<AppName>
- Unix:
/usr/local/share/<AppName> or /usr/share/<AppName>
- Win XP:
C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
- Vista:
(Fail! “C:\ProgramData” is a hidden *system* directory on Vista.)
- Win 7:
C:\ProgramData\<AppAuthor>\<AppName> # Hidden, but writeable on Win 7.
- Mac OS X:
For *nix, this is using the
$XDG_DATA_DIRS
default.Note
On linux, the $XDG_DATA_DIRS environment variable may contain a list. site_data_dir returns the first element of this list. If you want access to the whole list, use
site_data_dir_list()
Warning
Do not use this on Windows Vista. See the Vista-Fail note above for why.
Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the site data dir for this application.
Return type:
-
site_data_dir_list
(app_name, app_author, version=None, use_virtualenv=True, create=False)[source]¶ Return the list of full path to the OS wide data directories for this application.
- Typical site data directories are:
- Mac OS X:
/Library/Application Support/<AppName>
- Unix:
/usr/local/share/<AppName> or /usr/share/<AppName>
- Win XP:
C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
- Vista:
(Fail! “C:\ProgramData” is a hidden *system* directory on Vista.)
- Win 7:
C:\ProgramData\<AppAuthor>\<AppName> # Hidden, but writeable on Win 7.
- Mac OS X:
For *nix, this is using the
$XDG_DATA_DIRS
default.Warning
Do not use this on Windows Vista. See the Vista-Fail note above for why.
Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: A list to the full paths for site data directories for this application.
Return type:
-
site_config_dir
(app_name, app_author, version=None, use_virtualenv=True, create=False)[source]¶ Return the full path to the OS wide config dir for this application.
- Typical site data directories are:
- Mac OS X:
/Library/Application Support/<AppName>
- Unix:
/usr/local/share/<AppName> or /usr/share/<AppName>
- Win XP:
C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
- Vista:
(Fail! “C:\ProgramData” is a hidden *system* directory on Vista.)
- Win 7:
C:\ProgramData\<AppAuthor>\<AppName> # Hidden, but writeable on Win 7.
- Mac OS X:
For *nix, this is using the
$XDG_DATA_DIRS
default.Note
On linux, the $XDG_CONFIG_DIRS environment variable may contain a list. site_config_dir returns the first element of this list. If you want access to the whole list, use
site_config_dir_list()
Warning
Do not use this on Windows Vista. See the Vista-Fail note above for why.
Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: the full path to the site config dir for this application.
Return type:
-
site_config_dir_list
(app_name, app_author, version=None, use_virtualenv=True, create=False)[source]¶ Return the list of full path to the OS wide data directories for this application.
- Typical site data directories are:
- Mac OS X:
/Library/Application Support/<AppName>
- Unix:
/usr/local/share/<AppName> or /usr/share/<AppName>
- Win XP:
C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
- Vista:
(Fail! “C:\ProgramData” is a hidden *system* directory on Vista.)
- Win 7:
C:\ProgramData\<AppAuthor>\<AppName> # Hidden, but writeable on Win 7.
- Mac OS X:
For *nix, this is using the
$XDG_DATA_DIRS
default.Warning
Do not use this on Windows Vista. See the Vista-Fail note above for why.
Parameters: - app_name (str) – Name of the application. Will be appended to the base user config path.
- app_author (str) – Only used in Windows, name of the application author.
- version (str) – If given, the application version identifier will be appended to the app_name.
- use_virtualenv (bool) – If True and we’re running inside of a virtualenv, return a path relative to that environment.
- create (bool) – If True, the folder is created if it does not exist before the path is returned.
Returns: A list to the full paths for site data directories for this application.
Return type: