API

get_xdg_data_dirs() → list[str]

Get all XDG DATA DIRS

Returns:

The list of XDG data Dirs

Return type:

list[str]

get_icon_path(icon_name: str) → str | None

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

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

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

Defines the return type for get_validation_messages()

Error: list[str]
FutureError: list[str]
Warning: list[str]
Hint: list[str]
class InstallWithPortalResponse

Defines the return type for install_with_portal()

Name: str
Icon: bytes
exception InstallWithPortalsNotAvailable

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

Return type:

None

exception InstallWithPortalError(message: str)

Raised by install_with_portal() when an error occures

Parameters:

message (str)

Return type:

None

exception InstallWithPortalsCanceled

Raised by install_with_portal() when the User canceled the Installation

Return type:

None

exception InvalidDesktopEntry

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

Return type:

None

class TranslatableKey

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

Returns the text for the current system language

Returns:

The text

Return type:

str

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

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

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

Parameters:

entry_key (str)

Return type:

str

clear() → None

Clear

Return type:

None

class TranslatableListKey

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

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

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

Parameters:

entry_key (str)

Return type:

str

clear() → None

Clear

Return type:

None

class DesktopAction

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])

Load the Action from a Dict. Onyl used internaly.

Parameters:

action_section (dict[str, str])

get_text() → str

Converts the Action into a String

Return type:

str

get_icon_path() → str | None

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]

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

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

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

Returns all messages from desktop-file-validate

Returns:

A dict which contains the validation messages

Return type:

ValidationMessageDict

should_show() → bool

Returns if Desktop Entry should be showed

Return type:

bool

should_show_in_menu() → bool

Returns if a dektop entry should be displayed in the menu

Return type:

bool

get_icon_path() → str | None

Returns the full path to the Icon

Return type:

str | None

get_working_directory() → str

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]

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

Checks if the Desktop Entry is empty

Return type:

bool

get_text() → str

Returns the content of the Desktop Entry

Return type:

str

write_file(path: str | PathLike) → None

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

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

The name and the icon of the shortcut

Return type:

InstallWithPortalResponse

classmethod from_string(text: str) → DesktopEntry

Loads the content of a .desktop file from a string

Parameters:

text (str)

Return type:

DesktopEntry

classmethod from_file(path: str | PathLike) → DesktopEntry

Returns a Desktop Entry from the given file

Parameters:

path (str | PathLike)

Return type:

DesktopEntry

classmethod from_id(desktop_id: str) → DesktopEntry | None

Returns a Desktop Entry from the given id

Parameters:

desktop_id (str)

Return type:

DesktopEntry | None

static get_keywords() → list[str]

Returns the list of Keywords of a Desktop Entry

Returns:

The list of Keys

Return type:

list[str]

class DesktopEntryCollection

Represents a Collection of multiple Desktop Entries

desktop_entries: dict[str, DesktopEntry]

The desktop entries

load_file(path: str | PathLike) → None

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

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

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

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

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]

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]

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]

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]

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

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