Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Distutils extensions for KDE applications

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 kdedistutils
Octocat-spinner-32 .gitignore
Octocat-spinner-32 README.rst
README.rst

KDE extensions for distutils/setuptools

kdedistutils extends distutils/setuptools with support for KDE applications. It provides support for extracting and updating translations from Python sources and Qt designer files, and installs various kinds of KDE-related files (e.g. service descriptions, icons, translations, etc.) to the right place.

To use kdedistutils, just add it as submodule to your git repository:

git submodule add git://github.com/lunaryorn/kdedistutils.git kdedistutils

And import setup from kdedistutils:

import os
import sys
sys.path.append(os.path.abspath('kdedistutils'))

from kdedistutils import setup

setup(
    name='synaptiks',
    version=str(synaptiks.__version__),
    # ...
    )

Moreover you have to add the module to your source distribution by adding the following line to MANIFEST.in:

recursive-include kdedistutils/ *.py

Installation of KDE files

Handbooks

To install a standard KDE handbook in DocBook format, set kde_handbook to the relative path of your main source file:

setup(
    # ...
    kde_handbook='doc/handbook/index.docbook',
    )

Upon installation, it will generate the search index for this handbook, and install all *.docbook and *.png files in the same directory (doc/handbook/ in this case) to the KDE handbook installation directory.

Icons

To install icons, set the kde_icons keyword to a list of icons to install:

from kdedistutils.kde import ThemeIcon, StandAloneIcon

def setup(
    # ...
    kde_icons=[
        ThemeIcon('hicolor', 'scalable', 'apps', 'pics/synaptiks.svgz'),
        StandAloneIcon('pics/off-overlay.svgz')]
    )

Each entry in this list is either a StandAloneIcon or a ThemeIcon.

Standalone icons are installed to the application data directory (appdata resource type), the only argument is the relative path of the icon file in the source directory as string.

Themeable icons are installed to the directory of the icon theme. The ThemeIcon class takes four arguments:

theme
The name of the theme the icon belongs to as string (normally hicolor)
size
The icon size as string (e.g. 16x16, 32x32, etc.). For scalable SVG graphics, use 'scalable' as size.
category
The icon category as string (e.g. actions, mimetypes, etc.). The application icon goes into the apps category.
filename
The relative path of the icon file in the source directory as string.

Other files

To install other kinds of files, use the kde_files keyword. It is a dictionary, mapping resource types to lists of files to install. See kde4-config --types for a list of all resource types.

The most important resource types are explained in the following.

Application desktop entries

Use the resource type xdgdata-apps to install a desktop-independent desktop entry for your application to make it appear in the applications menu:

setup(
    # ...
    kde_files={
        'xdgdata-apps': ['synaptiks.desktop'],
        # ...
        }
    )

Application-specific data files

Normally, application-specific data files for Python modules are installed as package data. KDE specific data files however must be installed as appdata:

setup(
    # ...
    kde_files={
        'appdata': ['services/kcm_synaptiks.py', 'synaptiks.notifyrc'],
         # ...
        },
    )

This especially affects icons and notification configurations (synaptiks.notifyrc in the example above), because they are used by the KDE libraries, and thus expected to be in the appdata directory.

You specify prefixes for the destination, in order to install files into specific sub-directories:

setup(
    # ...
    kde_files={
        'appdata': [('pics/some_icon.png', 'icons')],
         # ...
        },
    )

Note the tuple: The first component is the filename as present in your source tree, the second is a directory name (may contain slashes for additional levels), which is prepended to the filename upon installation. The above would install pics/some_icon.png to /usr/share/apps/<appname>/icons/some_icon.png.

Services

To install service desktop entries (e.g. for SystemSettings modules), use the resource type services:

setup(
    # ...
    kde_files={
        'services': ['services/kcm_synaptiks.desktop'],
        # ...
        }
    )

Using the same features as aforementioned, you can install special services like for instance Dolphin service menus:

setup(
    # ...
    kde_files={
        'services': [('services/shark_servicemenu.desktop', 'ServiceMenus')],
        # ...
        }
    )

The above would install shark_servicemenu.desktop to /usr/share/kde4/services/ServiceMenus/.

Autostart files

To install desktop entries for autostart, use either autostart or xdgconf-autostart. The former is the KDE-specific autostart directory, autostart entries installed to this directory will only be executed by KDE. The latter is for desktop-independent autostart files. All XDG-compliant desktop environments will start autostart entries installed to xdgconf-autostart:

setup(
    # ...
    kde_files={
        'autostart': ['autostart/synaptiks_autostart.desktop']
        'xdgconf-autostart': ['autostart/synaptiks_init_config.desktop'],
        # ...
        },
    )

Localization support

kdedistutils also provides three commands to handle translations for a KDE application.

Message extraction

Use the extract_messages to extract translatable messages into a gettext template file. Messages are extracted from

  • All installed python packages
  • All Qt designer files installed as package_data (requires extractrc from kdesdk-scripts)
  • All Python files installed as kde_files

The command takes the following options:

--xgettext-exe        Path to xgettext
--extractrc-exe       Path to extractrc
--directory           The locale directory ("po/" by default)
--msgid-bugs-address  Mail address for bug reports concerning messages

The template file is stored in the locale directory, as <name>.pot where <name> is the name of the distribution (as given by the name keyword).

msgid-bugs-address is a email address intended for bug reports concerning the messages in your sources (not the translations!). It should be configured in your setup.cfg:

[extract_messages]
msgid-bugs-address = message-bugs@example.com

Catalog creation

To create a new catalog from the template file, use init_catalog. This command takes a locale (by default the current one) and the template file, and creates a new catalog to provide translations for this locale:

--msginit-exe    Path to msginit
--directory      The locale directory
--template-file  Input filename (template catalog)
--locale         Locale name

The --template-file defaults to the one created by extract_messages.

The command will ask for your email address and create a the new catalog as <locale>.po in the locale directory (where <locale> is the given locale).

Catalog updates

To update existing catalogs from the template file, use update_catalog. You can either update a specific catalog by given --locale, or update all catalogs (the default):

--directory      The locale directory
--locale         Locale name
--msgmerge-exe   Path to msgmerge
--template-file  Input filename (template catalog)

If --locale is not given, all catalogs are updated. Otherwise only the catalog for the given locale is updated.

Catalog compilation and installation

During package installation, the catalogs are automatically compiled and installed to the correct message directory.

Example

The examples in this document are taken from synaptiks. Take a look at its setup.py to see kdedistutils in the wild.

Gotchas

If easy_install is used to install the package, KDE files and translations will not be installed. This is because easy_install installs packages as Eggs into their own, self-contained directory.

To correctly install the files with easy_install, use easy_install --single-version-externally-managed. This option is implied by --root.

Generally, it is recommended to use pip instead of easy_install.

Something went wrong with that request. Please try again.