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

class Platform[source]

Bases: enum.Enum

WINDOWS = 1
MACOS = 2
POSIX = 3
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:

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

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

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

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

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

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:

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

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:

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

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:

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

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:

list