libdesktop

OS and desktop integration made easy.

libdesktop is a library that makes it easy to integrate into the OS, without worrying about its quirks. It aims to provide a common interface to different OSes, for things ranging from default applications to user directories to startup to sound.

Supports Windows (7+), OS X and Linux/Unix.

• Index

Installing libdesktop

Simply run: pip install libdesktop to get the last release.

Install from Git: pip install git+git://github.com/bharadwaj-raju/libdesktop.git

In the source directory: python setup.py install (or make install)

Description of the Modules

libdesktop has an array[] of different modules.

Here is a list of them, with descriptions.

libdesktop.applications

Documentation

Use for interacting with the system’s installed applications.

This handles things like launching/getting default/user-preffered apps. Also has a OS X-specific function: mac_app_exists().

libdesktop.startup

Documentation

Use for interacting with user startup.

This handles listing, adding and removing of applications to run at startup.

libdesktop.wallpaper

Documentation

This handles getting and setting of the wallpaper.

libdesktop.system

Documentation

Functions for the system in general.

This handles things like processes, executables, system name and configuration directories.

libdesktop.desktopfile

Documentation

Use for processing .desktop files.

This handles execution, parsing, location and construction of .desktop files.

libdesktop.volume

Documentation

Functions for system volume.

Set, get, increase, decrease etc. the volume.

libdesktop.dialog

Documentation

Native system dialogs for files, printing etc.

libdesktop.directories

Documentation

Functions for system ans user directories.

libdesktop.applications

A module for interacting with system applications.

libdesktop.applications.mac_app_exists(app)

Check if ‘app’ is installed (OS X).

Check if the given applications is installed on this OS X system.

Parameters:app (str) – The application name. Returns:Is the app installed or not? Return type:bool

libdesktop.applications.open_file_with_default_program(file_path, background=False, return_cmd=False)

Opens a file with the default program for that type.

Open the file with the user’s preferred application.

Parameters:

• file_path (str) – Path to the file to be opened.
• background (bool) – Run the program in the background, instead of waiting for completion. Defaults to False.
• return_cmd (bool) – Returns the command to run the program (str) instead of running it. Defaults to False.

Returns:

Only if return_cmd, the command to run the program is returned instead of running it. Else returns nothing.

Return type:

str

libdesktop.applications.terminal(exec_='', background=False, shell_after_cmd_exec=False, keep_open_after_cmd_exec=False, return_cmd=False)

Start the default terminal emulator.

Start the user’s preferred terminal emulator, optionally running a command in it.

Order of starting

Windows:

Powershell

Mac:

• iTerm2
• Terminal.app

Linux/Unix:

• $TERMINAL
• x-terminal-emulator
• Terminator
• Desktop environment’s terminal
• gnome-terminal
• urxvt
• rxvt
• xterm

Parameters:

• exec_ (str) – An optional command to run in the opened terminal emulator. Defaults to empty (no command).
• background (bool) – Run the terminal in the background, instead of waiting for completion. Defaults to False.
• shell_after_cmd_exec (bool) – Start the user’s shell after running the command (see exec_). Defaults to False.
• return_cmd (bool) – Returns the command used to start the terminal (str) instead of running it. Defaults to False.

Returns:

Only if return_cmd, returns the command to run the terminal instead of running it. Else returns nothing.

Return type:

str

libdesktop.applications.text_editor(file='', background=False, return_cmd=False)

Starts the default graphical text editor.

Start the user’s preferred graphical text editor, optionally with a file.

Parameters:

• file (str) – The file to be opened with the editor. Defaults to an empty string (i.e. no file).
• background (bool) – Runs the editor in the background, instead of waiting for completion. Defaults to False.
• return_cmd (bool) – Returns the command (str) to run the editor instead of running it. Defaults to False.

Returns:

Only if return_cmd, the command to run the editor is returned. Else returns nothing.

Return type:

str

libdesktop.desktopfile

A module for parsing, executing and finding .desktop files (the Linux/XDG standard for application information).

.desktop file Specification, published by XDG/Freedesktop.

libdesktop.desktopfile.construct(name, exec_, terminal=False, additional_opts={})

Construct a .desktop file and return it as a string. Create a standards-compliant .desktop file, returning it as a string. :param name: The program’s name. :type name: str :param exec_: The command. :type exec_: str :param terminal: Determine if program should be run in a terminal emulator or not. Defaults to False. :type terminal: bool :param additional_opts: Any additional fields. :type additional_opts: dict

Returns:The constructed .desktop file. Return type:str

libdesktop.desktopfile.execute(desktop_file, files=None, return_cmd=False, background=False)

Execute a .desktop file. Executes a given .desktop file path properly. :param desktop_file: The path to the .desktop file. :type desktop_file: str :param files: Any files to be launched by the .desktop. Defaults to empty list. :type files: list :param return_cmd: Return the command (as str) instead of executing. Defaults to False. :type return_cmd: bool :param background: Run command in background. Defaults to False. :type background: bool

Returns:Only if return_cmd. Returns command instead of running it. Else returns nothing. Return type:str

libdesktop.desktopfile.locate(desktop_filename_or_name)

Locate a .desktop from the standard locations. Find the path to the .desktop file of a given .desktop filename or application name. Standard locations:

• ~/.local/share/applications/
• /usr/share/applications

Parameters:desktop_filename_or_name (str) – Either the filename of a .desktop file or the name of an application. Returns:A list of all matching .desktop files found. Return type:list

libdesktop.desktopfile.parse(desktop_file_or_string)

Parse a .desktop file. Parse a .desktop file or a string with its contents into an easy-to-use dict, with standard values present even if not defined in file. :param desktop_file_or_string: Either the path to a .desktop file or a string with a .desktop file as its contents. :type desktop_file_or_string: str

Returns:A dictionary of the parsed file. Return type:dict

libdesktop.system

A module for general interaction with the system, like processes or executables.

libdesktop.system.get_cmd_out(command)

Get the output of a command.

Gets a nice Unicode no-extra-whitespace string of the stdout of a given command.

Parameters:command (str or list) – A string of the command, or a list of the arguments (as would be used in subprocess.Popen).

Note

If command is a str, it will be evaluated with shell=True i.e. in the default shell (for example, bash).

Returns:The stdout of the command. Return type:str

libdesktop.system.get_name()

Get desktop environment or OS.

Get the OS name or desktop environment.

List of Possible Values

Returns:The name of the desktop environment or OS. Return type:str

libdesktop.system.is_in_path(program)

Check if a program is in the system PATH.

Checks if a given program is in the user’s PATH or not.

Parameters:program (str) – The program to try to find in PATH. Returns:Is the program in PATH? Return type:bool

libdesktop.system.is_running(process)

Check if process is running.

Check if the given process name is running or not.

Note

On a Linux system, kernel threads (like kthreadd etc.) are excluded.

Parameters:process (str) – The name of the process. Returns:Is the process running? Return type:bool

libdesktop.startup

A module for interacting with the system startup.

libdesktop.startup.add_item(name, command, system_wide=False)

Adds a program to startup.

Adds a program to user startup.

Parameters:

• name (str) – The name of the startup entry.
• command (str) – The command to run.
• system_wide (bool) – Add to system-wide startup.

Note

system_wide requires superuser/admin privileges.

libdesktop.startup.list_items(system_wide=False)

List startup programs.

List the programs set to run at startup.

Parameters:system_wide (bool) – Gets the programs that run at system-wide startup. Returns:A list of dictionaries in this format:

{
  'name': 'The name of the entry.',
  'command': 'The command used to run it.'
}

Return type:list

libdesktop.startup.remove_item(name, system_wide=False)

Removes a program from startup.

Removes a program from startup.

Parameters:

• name (str) – The name of the program (as known to the system) to remove. See :func:list_items.
• system_wide (bool) – Remove it from system-wide startup.

Note

system_wide requires superuser/admin privileges.

libdesktop.wallpaper

A module for getting and setting the desktop wallpaper.

Supports Windows (7+), OS X and 99% of Linux desktops.

libdesktop.wallpaper.get_wallpaper()

Get the desktop wallpaper.

Get the current desktop wallpaper.

Returns:The path to the current wallpaper. Return type:str

libdesktop.wallpaper.set_wallpaper(image)

Set the desktop wallpaper.

Sets the desktop wallpaper to an image.

Parameters:image (str) – The path to the image to be set as wallpaper.

libdesktop.volume

A module for interacting with the system audio volume.

libdesktop.volume.decrease_volume(percentage)

Decrease the volume.

Decrease the volume by a given percentage.

Parameters:percentage (int) – The percentage (as an integer between 0 and 100) to decrease the volume by. Raises:ValueError – if the percentage is >100 or <0.

libdesktop.volume.get_volume()

Get the volume.

Get the current volume.

Returns:The current volume (percentage, between 0 and 100). Return type:int

libdesktop.volume.increase_volume(percentage)

Increase the volume.

Increase the volume by a given percentage.

Parameters:percentage (int) – The percentage (as an integer between 0 and 100) to increase the volume by. Raises:ValueError – if the percentage is >100 or <0.

libdesktop.volume.is_muted()

Check if volume is muted.

Checks if the volume is muted.

Note

This does not check for volume == 0.

Returns:Is the volume muted? Return type:bool

libdesktop.volume.mute()

Mute the volume.

Mutes the volume.

libdesktop.volume.set_volume(percentage)

Set the volume.

Sets the volume to a given percentage (integer between 0 and 100).

Parameters:percentage (int) – The percentage (as a 0 to 100 integer) to set the volume to. Raises:ValueError – if the percentage is >100 or <0.

libdesktop.volume.unix_is_pulseaudio_server()

Check if PulseAudio is running as sound server.

Checks if PulseAudio is running as the sound server.

Returns:Is PulseAudio the sound server? Return type:bool

libdesktop.volume.unmute()

Unmute the volume.

Unmutes the system volume.

Note

On some systems, volume is restored to its previous level after unmute, or set to 100.

libdesktop.dialog

A module for native system dialogs (file, printing, etc).

dialog.files

Submodule for file dialogs (open, save, etc)

libdesktop.dialog.files.open_file(default_dir='~', extensions=None, title='Choose a file', multiple_files=False, directory=False)

Start the native file dialog for opening file(s).

Starts the system native file dialog in order to open a file (or multiple files).

The toolkit used for each platform:

Note on Dependencies

It depends on pywin32 for Windows (installed by default in Python for Windows) It depends on PyQt for KDE and LxQt (usually installed by default on these). It depends on PyGObject for GNOME etc. (virtually every Linux desktop has this). It depends on PyGTK for other desktops (not usually installed, so has a GTK+ 3 fallback).

Parameters:

• default_dir (str) – The directory to start the dialog in. Default: User home directory.
• extensions (dict) –

  The extensions to filter by. Format:

  {
    'Filter Name (example: Image Files)': ['*.png', '*.whatever', '*']
  }
  

• title (str) – The title of the dialog. Default: Choose a file
• multiple_files (bool) – Whether to choose multiple files or single files only. Default: False
• directory (bool) – Whether to choose directories. Default: False

Returns:

list of str s (each str being a selected file). If nothing is selected/dialog is cancelled, it is None.

Return type:

list

libdesktop.directories

A module for interacting with system and user directories.

libdesktop.directories.get_config_dir(program='', system_wide=False)

Get the configuration directory.

Get the configuration directories, optionally for a specific program.

Parameters:

• program (str) – The name of the program whose configuration directories have to be found.
• system_wide (bool) – Gets the system-wide configuration directories.

Returns:

A list of all matching configuration directories found.

Return type:

list

libdesktop.directories.get_config_file(program, system_wide=False)

Get the configuration file for a program.

Gets the configuration file for a given program, assuming it stores it in a standard location. See also get_config_dir().

Parameters:

• program (str) – The program for which to get the configuration file.
• system_wide (bool) – Whether to get the system-wide file for the program.

Returns:

A list of all matching configuration files found.

Return type:

list

libdesktop.directories.get_desktop_dir()

Get the user desktop directory.

Get the user directory for storing files on the Desktop.

Returns:The path to the user Desktop directory. Return type:str

libdesktop.directories.get_documents_dir()

Get the user directory for documents.

Get the user directory for storing documents.

Returns:The path to the user Documents directory. Return type:str

libdesktop.directories.get_downloads_dir()

Get the user directory for downloads.

Get the user directory for storing downloaded files.

Returns:The path to the user Downloads directory. Return type:str

libdesktop.directories.get_music_dir()

Get the user directory for music.

Get the user directory for storing music.

Returns:The path to the user Music directory. Return type:str

libdesktop.directories.get_pictures_dir()

Get the user directory for pictures.

Get the user directory for storing pictures.

Returns:The path to the user Pictures directory. Return type:str

libdesktop.directories.get_videos_dir()

Get the user directory for videos.

Get the user directory for storing videos.

Returns:The path to the user Videos directory. Return type:str

libdesktop.directories.windows_get_program_files_dir()

Get the Windows system Program Files directory.

Get the Windows system Program Files directory.

Returns:The path to the Windows system Program Files directory. Return type:str

libdesktop.directories.windows_get_program_files_x64_dir()

Get the Windows system Program Files (x64) directory.

Get the Windows system directory for storing 64-bit programs, that is, Program Files (x64).

Note

This will fail (possibly with an interpreter crash) on 32-bit systems, or a 32-bit Python.

Returns:The path to the Windows system Program Files (x64) directory. Return type:str

libdesktop.directories.windows_get_program_files_x86_dir()

Get the Windows system Program Files (x86) directory.

Get the Windows system directory for storing 32-bit programs on a 64-bit system, that is, Program Files (x86).

Note

This will return the normal Program Files directory (as given in windows_get_program_files_dir()) on a 32-bit system, or a 32-bit Python.

Returns:The path to the Windows system Program Files (x86) directory. Return type:str

libdesktop.directories.windows_get_public_dir()

Get the Windows system Public directory.

Get the Windows system Public directory.

Returns:The path to the system Public directory. Return type:str

libdesktop.directories.windows_get_system32_dir()

Get the Windows system System32 directory.

Get the Windows system System32 directory (example: C:/Windows/System32/)

Returns:The path to the Windows system System32 directory. Return type:str

libdesktop.directories.windows_get_windows_dir()

Get the Windows system directory.

Get the Windows system Windows directory (example: C:/Windows/)

Returns:The path to the Windows system Windows directory. Return type:str

Testing libdesktop

Libdesktop has tests in the tests/ directory.

Running the tests

1. Install pytest: pip install pytest.
2. Run make test.

Customization of the tests

By default, the tests do not run GUI applications (like in the applications module functions).

To run them, set the environment variable LIBDESKTOP_TESTS_RUN_GUI to true.