PyKDE Extensions"> ]> Simon Edwards

simon@simonzone.com

2005 Simon Edwards &FDLNotice; 2005-09-19 0.4 &appname; is a collection of software and Python packages to support the creation and installation of KDE applications. KDE PyKDE Extensions python PyKDE &appname; is a collection of software and Python packages to support the creation and installation of KDE applications. C++ projects on KDE traditionally use autoconf, automake and libtool to handle the building and installation. These tools and difficult to use, even for experianced developers. Fortunately Python has a its own system for building and installing modules and software. Distutils is a standard Python package and comes with every Python installation. &appname; builds on Distutils with extensions tailored for handling KDE programs. A typical KDE program comes not only with the program itself but also extra files such as a manual written in Docbook format, translation files, icons, images and other auxiliary data files. &appname; provides support for handling all these other files types. It is advised that you first read the standard Distutils documentation to learn about how it works. &appname; adds some KDE specific extensions which are documented below. Distutils is based around writing a setup.py file which then uses the distutils package To use the KDE extensions, the first thing you need to do in your setup.py file is include the kdedistutils package. #!/usr/bin/env python # Setup.py file for MyKDEApplication import kdedistutils You need to call the setup() function from kdedistutils with all of the configuration information about your application, much like the standard setup() from distutils. kdedistutils.setup(name="pykdeextensions", version="0.1.0", author="Simon Edwards", author_email="simon@simonzone.com", url="http://www.simonzone.com/software/pykdeextensions/", min_kde_version = "3.0.0", min_qt_version = "3.0.0", license = "LGPL" ) min_kde_version and min_qt_version specify the minimum versions of the Qt library and KDE needed to install and run the software. These requirements are checked during install. The other arguments shown here are standard distutils.setup() arguments. Each KDE application as a data directory of it's own for storing any extra data files it may need to run. Data files are specified using the the application_data argument for setup(). application_data is a list of files to install. application_data = ['extracode.py', ('pics', ['pics/warning.png'])] You can simply specify the name of each file as a string and they will be installed directly in the application data directory. Or you can use a tuple containing the name of the sub-directory under the application data directory to install into, and as the second tuple item, the list of files to install into the given sub-directory. Since most large Python programs are broken up into multiple source files it is recommended that all of the Python files that comprise your application be installed into the application directory. This helps eliminate problems with the Python module path and the interpreter not being able find the correct file to import. Even with all of the python files in the Application data directory, it is still desirable to have your application's "executables" available in KDE's bin directory. &appname; provides an easy way for creating symbolic links from the "bin" directory to scripts in the application directory. executable_links = [('myapplication','myapplication.py'), ('myapplicationgui','myapplicationgui.py')] This example specifies an executable symbolic link myapplication that points to the myapplication.py script in the application data directory. Standard Distutils does not feature an uninstall command. &appname; does and it can be easily invoked with: python setup.py uninstall It is quite basic. The install writes the list of files it installed to the file install_log.txt. The uninstall command simply reads this file and removes the files and directories that are listed within. Docbook is an XML based file format for writing manuals and books. More information about using Docbook to write manuals and documentation using Docbook is here. Manuals are written in the Docbook format, but need to be converted into HTML when installed and made available for the KDE Help Center. Docbooks files and images are usually organised under a doc directory which is then further divided by two letter language code. For example doc/en, doc/nl, en doc/fr. The Docbook files themselves are named index.docbook By using the docbooks argument to setup() in your setup.py, you can specify the directories containing docbook files. You also need to specify the language used in that directory. docbooks = [ ('doc/en','en'), ('doc/nl','nl'), ('doc/fr','fr') ] The argument to docbooks is a list of tuples. The first item of a tuple is the relative path to a docbook directory. The second item is the two letter language code. Docbook files specified this way will automatically be converted to HTML during install. Qt-Designer is a graphical application used for designing user interfaces. It creates .ui files. These files need to be converted into Python classes before they can be used in a Python application. This can be manually done using the pyuic command from the shell. But it is a lot more convenient to let &appname; to this automatically for you. All you need to do is import the qtdesigner or kdedesigner module, depending on whether your application is pure Qt or uses KDE, and then you can import your user interface files as though they were normal Python files. #!/usr/bin/env python from tdeui import * import kdedesigner # This module lets us import .ui file directly. from MyWindow import * # Loads MyWindow.ui # Subclass the Qt-designer form. class MyWindowCode(MyWindow): # Implement extra functionality and methods. The kdedesigner/qtdesigner module converts .ui on demand to .py files. i18n (an abbreviation of internationalization) is the process of translating the user interface and documentation of a piece of software into another language. i18n.kde.org is the central information point for the effort to translate KDE software into other languages. Translation of the user interface an application is done using .pot files and .po files. A .pot file, is generated from the source code of the program itself, and contains all of the strings / fragments of text, that are used in the program. Before a string in a program is include in the .pot file, it needs to be marked with the i18n(). #!/usr/bin/env python from kdecode import * ... mylabel = QLabel(i18n("Select new directory:")) ... The i18n() is part of the kdecode package and needs to be imported. &appname; provides support for generating .pot files and managing and updating .po files. By using the i18n argument to setup() in your setup.py, you can specify the directory that should contain the .pot and .po files. The argument for i18n is a tuple. The first item is the relative path to the directory where the translation files should be stored. The second item is a list of directories that should be scanned for Python source files containing translatable strings. i18n = ('po',['.','mymodule']) Once your setup.py is configured, use this command in the shell to generate the .pot file. python setup.py update_messages This command also updates any already existing .po files with any new messages. &appname; also handles installing translation files and converting .po files into the special binary format needed by the application at runtime. &appname; can also help create modules for the KDE Control Center. C++ glue code is needed when writing in module in Python. Fortunately &appname; can generate this glue for you automatically. The best way to start learning about creating modules is to read the KConfig Module HOWTO. It is written for C++, but the concepts are the same for Python. In your setup.py file you can specify the list of kcontrol modules that need to be installed. kcontrol_modules = [ ('src/kcontrol_module.desktop','kcontrol_module.py')] ) This is just a list of tuples. The first item is name of the .desktop file that you've made for your module. The second item is the name of the Python program to run when the user views the module in kcontrol. This program is expected to be in the application's data files directory. The KControl Module Guidelines provides useful information about how to design a KControl module that fits into the rest of KDE. &appname; typically installs the .desktop file into the /usr/share/applications/kde/ directory. This is normally enough to make the module appear in the KDE Control Center. But for some distributions, most notably Mandriva but probably others too, this isn't enough. Mandriva in particular uses the Debian menu system for managing the K menu and also for KControl modules. In order to get a module to appear in the kcontrol it is best to createa a .menu file and copy it into /usr/lib/menu, and then use update-menus as root to update all of the menus and the list of kcontrol modules. Right now there is no support for "module-testing" or "X-KDE-Test-Module=true" features in .desktop files. &appname; can be used for the creation of kio-slaves. &appname; handles the C++ glue code needed for making kioslaves in Python. developer.kde.org has some documentation about KIO-slaves aimed at C++ programmers. In your setup.py file you can specify the list of kioslaves that need to be installed. kioslaves = [ ('src/kioslave.protocol','kioslave.py')] ) This is just a list of tuples. The first item is name of the .protocol file that you've made for your kio-slave. The second item is the name of the Python program to run when the user views the module in kcontrol. This program is expected to be in the application's data files directory. The app_templates directory contains a number of application templates. An application template is just a collection of files in a directory structure that should be copied and used as starting point when developing a new application. An application template typically contains default documentation files, icons, source file and setup.py file which can later be modified. Every application template has a number of files in common. They are described below. AUTHORS Lists the authors of this software. ChangeLog An itemised log or list of changes to the software. COPYING A copy of the GNU GPL, explaining the terms under which this software may be distributed. This file does not need to be changed. INSTALL Instructions for installing the software. MANIFEST.in NEWS News about what is new in the current version of this software. README Important instructions and information that the user should read first. setup.py . TODO List of features and work that may be available in a future version of the software. po/ This directory is initially empty. It is used for .pot and .po translation files. doc/ This directory is initially empty. It is used for holding the directores for the different langauge version of the manual. doc/en This directory for the english version of the manual. doc/en/index.docbook The english manual in docbook format. The default is a template which can then be filled in. src This directory containing the source code for the software. The default contents of this directory depends on the particular application template. The kdeutility application template is a simple utility that uses an interface designed in Qt-Designer. It doesn't have a menubar or toolbar. The kdeapp application template is an application with menubar, toolbar and separated document and view classes. The menubar and toolbars are defined using XML. The kcontrol_module application template is a simple module for the KDE Control Center. The module can also be run as a separate application outside of KControl to ease development and debugging. The kioslave application template is a simple KIO-slave that implements a simple RAM disk. Once installed it can be accessed using kioslave:/ in konqueror. It is initially empty. Files and directories can be made and deposited. kioslave.py contains more information and comments. Note that the KIO subsystem usually creates multiple running instances of a kio-slave backend. For the application template, files and directories are specific to each particular backend instance. When using konqueror the same instance will be used, but if you try to access kioslave:/ from a different process a new (empty!) instance will be craeted. This can be confusing! Be aware. &appname; Program copyright 2005 Simon Edwards simon@simonzone.com Contributors: Konqui the KDE Dragon konqui@kde.org Tux the Linux Penguin tux@linux.org Documentation copyright 2005 Simon Edwards simon@simonzone.com &underFDL; &documentation.index;