API#

get_xdg_data_dirs() → list[str][source]#

Get all XDG DATA DIRS

Returns:: The list of XDG data Dirs
Return type:: list[str]

get_icon_path(icon_name: str) → str | None[source]#

Get the path of a Icon

Parameters:: icon_name (str) – The name of the Icon as found in the desktop entry
Returns:: The full path to the Icon. none if the Icon was not found.
Return type:: str | None

is_action_identifier_valid(identifier: str) → bool[source]#

Checks if a Action identifier is valid

Parameters:: identifier (str) – The Identifier
Returns:: If the identifier is valid
Return type:: bool

is_custom_key_name_valid(name: str) → bool[source]#

Checks if the given name can be used for a custom key

Parameters:

identifier – The name
name (str) –

Returns:

If the name can be used

Return type:

bool

class ValidationMessageDict[source]#

Defines the return type for get_validation_messages()

Error: list[str]#

FutureError: list[str]#

Warning: list[str]#

Hint: list[str]#

class InstallWithPortalResponse[source]#

Defines the return type for install_with_portal()

Name: str#

Icon: bytes#

exception InstallWithPortalsNotAvailable[source]#

Raised by install_with_portal() when the DynamicLauncher portal is not available

Return type:: None

exception InstallWithPortalError(message: str)[source]#

Raised by install_with_portal() when an error occures

Parameters:: message (str) –
Return type:: None

exception InstallWithPortalsCanceled[source]#

Raised by install_with_portal() when the User canceled the Installation

Return type:: None

exception InvalidDesktopEntry[source]#

This Exception is raised, when a invalid Desktop Entry is loaded

Return type:: None

class TranslatableKey[source]#

Represents a Key in a Desktop Entry, that can be translated into different languages

default_text: str#: The untranslated text

translations: dict[str, str]#: The translations

get_translated_text() → str[source]#

Returns the text for the current system language

Returns:: The text
Return type:: str

load_section(section: dict[str, str], search_key: str) → None[source]#

Loads a section from a Desktop Entry. Only for internal use.

Parameters:

section (dict[str, str]) –
search_key (str) –

Return type:

None

get_text(entry_key: str) → str[source]#

Returns the text for saving a Desktop Entry. only for internal use.

Parameters:: entry_key (str) –
Return type:: str

clear() → None[source]#

Clear

Return type:: None

class TranslatableListKey[source]#

Represents a List in a Desktop Entry, that can be translated into different languages

default_list: list[str]#: The unstranslated list

translations: dict[str, list[str]]#: The translated lists

load_section(section: dict[str, str], search_key: str) → None[source]#

Loads a section from a Desktop Entry. Only for internal use.

Parameters:

section (dict[str, str]) –
search_key (str) –

Return type:

None

get_text(entry_key: str) → str[source]#

Returns the text for saving a Desktop Entry. only for internal use.

Parameters:: entry_key (str) –
Return type:: str

clear() → None[source]#

Clear

Return type:: None

class DesktopAction[source]#

Represents a Action in a Desktop Entry

Name: TranslatableKey#: The Name Key

Icon: str | None#: The Icon Key

Exec: str | None#: The Exec Key

classmethod from_dict(action_section: dict[str, str])[source]#

Load the Action from a Dict. Onyl used internaly.

Parameters:: action_section (dict[str, str]) –

get_text() → str[source]#

Converts the Action into a String

Return type:: str

get_icon_path() → str | None[source]#

Returns full Path to the Icon

Returns:: The full Path or None, if the Icon can’t be found
Return type:: str | None

get_command(file_list: list[str] | None = None, url_list: list[str] | None = None) → list[str][source]#

Returns the command to start this action. Returns an empty list if the Exec Key is not set. Take a look at the tutorial for more information.

Parameters:

file_list (list[str] | None) – A list of local files
url_list (list[str] | None) – A list of URLs

Returns:

The command

Return type:

list[str]

class DesktopEntry[source]#

Represents a Desktop Entry

Type: Literal['Application', 'Link', 'Directory']#: The Type Key

Version: Literal['1.0', '1.1', '1.2', '1.3', '1.4', '1.5'] | None#: The Version Key

Name: TranslatableKey#: The Name Key

GenericName: TranslatableKey#: The GenericName Key

NoDisplay: bool | None#: The NoDisplay Key

Comment: TranslatableKey#: The Comment Key

Icon: str | None#: The Icon Key

Hidden: bool | None#: The Hidden Key

OnlyShowIn: list[str]#: The OnlyShowIn Key

NotShowIn: list[str]#: The NotShowIn Key

DBusActivatable: bool | None#: The DBusActivatable Key

TryExec: str | None#: The TryExec Key

Exec: str | None#: The Exec Key

Path: str | None#: The Path Key

Terminal: bool | None#: The Terminal Key

MimeType: list[str]#: The MimeType Key

Categories: list[str]#: The Categories Key

Implements: list[str]#: The Implements Key

Keywords: TranslatableListKey#: The Keywords Key

StartupNotify: bool | None#: The StartupNotify Key

StartupWMClass: str | None#: The StartupWMClass Key

URL: str | None#: The URL Key

PrefersNonDefaultGPU: bool | None#: The PrefersNonDefaultGPU Key

SingleMainWindow: bool | None#: The SingleMainWindow Key

Actions: dict[str, DesktopAction]#: The Actions

CustomKeys: dict[str, str]#: The Keys starting with X-

file_path: str | None#: The path to the .desktop file

desktop_id: str | None#: The ID of the .desktop file

leading_comment: str | None#: If you set this, the given Comment will be added at the top of the Desktop Entry. You can use it for stuff like ‘Created with foo’.

is_valid() → bool[source]#

Returns, if the Desktop Entry is valid. desktop-file-validate needs to be installed.

Returns:: If the entry is valid
Return type:: bool

get_validation_messages() → ValidationMessageDict[source]#

Returns all messages from desktop-file-validate

Returns:: A dict which contains the validation messages
Return type:: ValidationMessageDict

should_show() → bool[source]#

Returns if Desktop Entry should be showed

Return type:: bool

should_show_in_menu() → bool[source]#

Returns if a dektop entry should be displayed in the menu

Return type:: bool

get_icon_path() → str | None[source]#

Returns the full path to the Icon

Return type:: str | None

get_working_directory() → str[source]#

Returns the working directory for this program. When the Path Key is set, the value of this Key is returned. If not, the Home directory is returned.

Returns:: The working directory
Return type:: str

get_command(file_list: list[str] | None = None, url_list: list[str] | None = None) → list[str][source]#

Returns the command to start this program. Returns an empty list if the Exec Key is not set. Take a look at the tutorial for more information.

Parameters:

file_list (list[str] | None) – A list of local files
url_list (list[str] | None) – A list of URLs

Returns:

The command

Return type:

list[str]

is_empty() → bool[source]#

Checks if the Desktop Entry is empty

Return type:: bool

get_text() → str[source]#

Returns the content of the Desktop Entry

Return type:: str

write_file(path: str | PathLike) → None[source]#

Writes a .desktop file

Parameters:: path (str | PathLike) –
Return type:: None

install_with_portal(window_dentifier: str, icon: bytes, *, editable_name: bool = True, editable_icon: bool = False) → InstallWithPortalResponse[source]#

Installs the entry using the DynamicLauncher Portal. Take a look at the tutorial for more information.

Parameters:

window_dentifier (str) – The Window Identifier
icon (bytes) – The Icon
editable_name (bool) – If the User should be able to edit the Name, defaults to True
editable_icon (bool) – If the User should be able to edit the Icon, defaults to False

Raises:

InstallWithPortalsNotAvailable – The DynamicLauncher portal is not available
InstallWithPortalError – A error occured
InstallWithPortalsCanceled – The user canceled the Installation
ModuleNotFoundError – jeepney is not installed

Returns:

The name and the icon of the shortcut

Return type:

InstallWithPortalResponse

classmethod from_string(text: str) → DesktopEntry[source]#

Loads the content of a .desktop file from a string

Parameters:: text (str) –
Return type:: DesktopEntry

classmethod from_file(path: str | PathLike) → DesktopEntry[source]#

Returns a Desktop Entry from the given file

Parameters:: path (str | PathLike) –
Return type:: DesktopEntry

classmethod from_id(desktop_id: str) → DesktopEntry | None[source]#

Returns a Desktop Entry from the given id

Parameters:: desktop_id (str) –
Return type:: DesktopEntry | None

static get_keywords() → list[str][source]#

Returns the list of Keywords of a Desktop Entry

Returns:: The list of Keys
Return type:: list[str]

class DesktopEntryCollection[source]#

Represents a Collection of multiple Desktop Entries

desktop_entries: dict[str, DesktopEntry]#: The desktop entries

load_file(path: str | PathLike) → None[source]#

Loads the given desktop entry file and adds it to the collection

Parameters:: path (str | PathLike) – The path to the desktop entry
Return type:: None

load_directory(path: str | PathLike) → bool[source]#

Loads all desktop entries from the given directory

Parameters:: path (str | PathLike) – The directory
Returns:: True if all desktop entries could be loaded, False if some couldn’t be loaded
Return type:: bool

load_menu() → bool[source]#

Loads all desktop entries from the menu

Returns:: True if all desktop entries could be loaded, False if some couldn’t be loaded
Return type:: bool

load_desktop() → bool[source]#

Loads all desktop entries files from the Desktop

Returns:: True if all desktop entries could be loaded, False if some couldn’t be loaded
Return type:: bool

load_autostart() → bool[source]#

Loads all autostart entries

Returns:: True if all desktop entries could be loaded, False if some couldn’t be loaded
Return type:: bool

get_entries_by_category(category: str) → list[DesktopEntry][source]#

Returns a list of all desktop entries that have the given category

Parameters:: category (str) – The category
Returns:: The list of desktop entries
Return type:: list[DesktopEntry]

get_entries_by_mime_type(mime_type: str) → list[DesktopEntry][source]#

Returns a list of all desktop entries that can open the given MimeType

Parameters:: mime_type (str) – The MimeType
Returns:: The list of desktop entries
Return type:: list[DesktopEntry]

get_visible_entries() → list[DesktopEntry][source]#

Returns a list of all desktop entries that should be shown to the User

Returns:: The list of desktop entries
Return type:: list[DesktopEntry]

get_menu_entries() → list[DesktopEntry][source]#

Returns a list of all desktop entries that should be shown in the Menu

Returns:: The list of desktop entries
Return type:: list[DesktopEntry]

get_entry_by_name(name: str, include_translations: bool = True) → DesktopEntry | None[source]#

Returns the entry with the given Name. Returns None if no Entry exists with this Name.

Parameters:

name (str) – The Name
include_translations (bool) – Search also the translations

Returns:

The Entry

Return type:

DesktopEntry | None