API - desktop-entry-lib 5.0 documentation

Skip to content
Back to top
View this page

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

      - 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

    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