PyXDG 0.26¶
PyXDG is a Python library supporting various freedesktop standards.
Contents:
Base Directories¶
The XDG Base Directory specification provides standard locations to store application data, configuration, and cached data.
Data directories¶
-
xdg.BaseDirectory.
save_data_path
(*resource)[source]¶ Ensure
$XDG_DATA_HOME/<resource>/
exists, and return its path. ‘resource’ should normally be the name of your application or a shared resource. Use this when saving or updating application data.
-
xdg.BaseDirectory.
load_data_paths
(*resource)[source]¶ Returns an iterator which gives each directory named ‘resource’ in the application data search path. Information provided by earlier directories should take precedence over later ones.
-
xdg.BaseDirectory.
xdg_data_home
¶ $XDG_DATA_HOME or the default,
~/.local/share
-
xdg.BaseDirectory.
xdg_data_dirs
¶ A list of directory paths in which application data may be stored, in preference order.
Configuration directories¶
-
xdg.BaseDirectory.
save_config_path
(*resource)[source]¶ Ensure
$XDG_CONFIG_HOME/<resource>/
exists, and return its path. ‘resource’ should normally be the name of your application. Use this when saving configuration settings.
-
xdg.BaseDirectory.
load_config_paths
(*resource)[source]¶ Returns an iterator which gives each directory named ‘resource’ in the configuration search path. Information provided by earlier directories should take precedence over later ones, and the user-specific config dir comes first.
-
xdg.BaseDirectory.
load_first_config
(*resource)[source]¶ Returns the first result from load_config_paths, or None if there is nothing to load.
-
xdg.BaseDirectory.
xdg_config_home
¶ $XDG_CONFIG_HOME or the default,
~/.config
-
xdg.BaseDirectory.
xdg_config_dirs
¶ A list of directory paths in which configuration may be stored, in preference order.
Cache directory¶
-
xdg.BaseDirectory.
save_cache_path
(*resource)[source]¶ Ensure
$XDG_CACHE_HOME/<resource>/
exists, and return its path. ‘resource’ should normally be the name of your application or a shared resource.
-
xdg.BaseDirectory.
xdg_cache_home
¶ $XDG_CACHE_HOME or the default,
~/.cache
Runtime directory¶
-
xdg.BaseDirectory.
get_runtime_dir
(strict=True)[source]¶ Returns the value of $XDG_RUNTIME_DIR, a directory path.
This directory is intended for ‘user-specific non-essential runtime files and other file objects (such as sockets, named pipes, …)’, and ‘communication and synchronization purposes’.
As of late 2012, only quite new systems set $XDG_RUNTIME_DIR. If it is not set, with
strict=True
(the default), a KeyError is raised. Withstrict=False
, PyXDG will create a fallback under /tmp for the current user. This fallback does not provide the same guarantees as the specification requires for the runtime directory.The strict default is deliberately conservative, so that application developers can make a conscious decision to allow the fallback.
New in version 0.25.
Desktop Entries¶
XDG Desktop Entry Specification
-
class
xdg.DesktopEntry.
DesktopEntry
(filename=None)[source]¶ Class to parse and validate Desktop Entries
-
__init__
(filename=None)[source]¶ Create a new DesktopEntry.
If filename exists, it will be parsed as a desktop entry file. If not, or if filename is None, a blank DesktopEntry is created.
-
new
(filename)[source]¶ Make this instance into a new, blank desktop entry.
If filename has a .desktop extension, Type is set to Application. If it has a .directory extension, Type is Directory. Other extensions will cause
ParsingError
to be raised.
-
parse
(file)[source]¶ Parse a desktop entry file.
This can raise
ParsingError
,DuplicateGroupError
orDuplicateKeyError
.
-
validate
(report='All')¶ Validate the contents, raising
ValidationError
if there is anything amiss.report can be ‘All’ / ‘Warnings’ / ‘Errors’
-
findTryExec
()[source]¶ Looks in the PATH for the executable given in the TryExec field.
Returns the full path to the executable if it is found, None if not. Raises
NoKeyError
if TryExec is not present.New in version 0.26.
-
getCategories
()[source]¶ -
getComment
()[source]¶ -
getExec
()[source]¶ -
getGenericName
()[source]¶ -
getHidden
()[source]¶ -
getIcon
()[source]¶ -
getMimeTypes
()[source]¶ -
getMiniIcon
()[source]¶ -
getName
()[source]¶ -
getNoDisplay
()[source]¶ -
getNotShowIn
()[source]¶ -
getOnlyShowIn
()[source]¶ -
getPath
()[source]¶ -
getProtocols
()[source]¶ -
getStartupNotify
()[source]¶ -
getStartupWMClass
()[source]¶ -
getTerminal
()[source]¶ -
getTerminalOptions
()[source]¶ -
getTryExec
()[source]¶ -
getType
()[source]¶ -
getURL
()[source]¶ -
getVersionString
()[source]¶ Convenience methods to get the values of specific fields. If the field is missing, these will simply return an empty or zero value. There are similar methods for deprecated and KDE specific keys, but these are not listed here.
-
Icon Themes¶
-
xdg.IconTheme.
getIconPath
(iconname, size=None, theme=None, extensions=['png', 'svg', 'xpm'])[source]¶ Get the path to a specified icon.
- size :
- Icon size in pixels. Defaults to
xdg.Config.icon_size
. - theme :
- Icon theme name. Defaults to
xdg.Config.icon_theme
. If the icon isn’t found in the specified theme, it will be looked up in the basic ‘hicolor’ theme. - extensions :
- List of preferred file extensions.
Example:
>>> getIconPath("inkscape", 32) '/usr/share/icons/hicolor/32x32/apps/inkscape.png'
-
xdg.IconTheme.
getIconData
(path)[source]¶ Retrieve the data from the .icon file corresponding to the given file. If there is no .icon file, it returns None.
Example:
getIconData("/usr/share/icons/Tango/scalable/places/folder.svg")
Recently used files¶
XDG recent file storage specification
-
class
xdg.RecentFiles.
RecentFiles
[source]¶ -
addFile
(item, mimetype, groups=None, private=False)[source]¶ Add a recently used file.
item should be the URI of the file, typically starting with
file:///
.
-
getFiles
(mimetypes=None, groups=None, limit=0)[source]¶ Get a list of recently used files.
The parameters can be used to filter by mime types, by group, or to limit the number of items returned. By default, the entire list is returned, except for items marked private.
-
-
class
xdg.RecentFiles.
RecentFile
[source]¶ -
URI
¶ The URI of the file; typically starts with
file:///
.
-
MimeType
¶ A Mime type, such as ‘text/plain’.
-
Timestamp
¶ Unix timestamp of when the file was added to the list.
-
Private
¶ Boolean indicating whether the entry is private, meaning that it will only be shown if it is in a selected group.
-
Groups
¶ A list of groups this entry belongs to.
-
Exceptions¶
Exception Classes for the xdg package
-
exception
xdg.Exceptions.
DuplicateGroupError
(group, file)[source]¶ Raised when the same key occurs twice in an INI-style file.
Attributes are .group and .file.
-
exception
xdg.Exceptions.
DuplicateKeyError
(key, group, file)[source]¶ Raised when the same key occurs twice in an INI-style file.
Attributes are .key, .group and .file.
-
exception
xdg.Exceptions.
NoGroupError
(group, file)[source]¶ Raised when trying to access a nonexistant group in an INI-style file.
Attributes are .group and .file.
-
exception
xdg.Exceptions.
NoKeyError
(key, group, file)[source]¶ Raised when trying to access a nonexistant key in an INI-style file.
Attributes are .key, .group and .file.
-
exception
xdg.Exceptions.
NoThemeError
(theme)[source]¶ Raised when trying to access a nonexistant icon theme.
The name of the theme is the .theme attribute.