Fortunately, the Nepomuk developers have come up with a high level API to query already stored metadata, and today’s post will deal with querying tags in Nepomuk. As per the past tutorials, the full source code is available in the kdeexamples module.

Let’s start off with the basic imports:

import sys

import PyQt4.QtCore as QtCore

import PyKDE4.kdecore as kdecore
import PyKDE4.kdeui as kdeui
from PyKDE4.kio import KIO
from PyKDE4.nepomuk import Nepomuk
from PyKDE4.soprano import Soprano

Then let’s create a simple class that wil be used for the rest of this exercise:

class NepomukTagQueryExample(QtCore.QObject):

    def __init__(self, parent=None):

        super(NepomukTagQueryExample, self).__init__(parent)

__init__ is just used to construct the instance, nothing more. The bulk of the work is in the query_tag() function, which we’ll take a look at in parts.

    def query_tag(self, tag):

        """Query for a specific tag."""

        tag = Nepomuk.Tag(tag)

First of all we convert the tag we want to query into a proper Nepomuk.Tag() instance. Of course we should use an already existing tag: even if Nepomuk.Tag() automatically creates new tags, it makes little sense to query for a newly created tag, doesn’t it?

For our job, we need to use properties which define the terms of our query. As we’re looking for tags, we’ll use Soprano.Vocabulary.NAO.hasTag():

        soprano_term_uri = Soprano.Vocabulary.NAO.hasTag()
        nepomuk_property = Nepomuk.Types.Property(soprano_term_uri)

The first call generates an URI pointing to a specific RDF resource for this specific term, which is then wrapped as a Nepomuk.Types.Property in the second call. While the C++ API docs don’t show this, I found it to be necessary, or the Python interpreter would raise a TypeError. Notice that this is not the only term we can use: aside for tags, there are a lot of other URIs we can use for querying, listed in the Soprano API docs.

Once we have our property set up, it’s time to define which kind of query we’re going to use. In this case, since we want to check for the presence of tags, we use a Nepomuk.Query.ComparisonTerm, which is a query term used to match values of specific properties (in our case, tags):

        comparison_term = Nepomuk.Query.ComparisonTerm(nepomuk_property,
                Nepomuk.Query.ResourceTerm(tag))

Our tag is wrapped in a ResourceTerm, which is used exactly for the purpose. Now we make the proper query: in this specific case, we want to look up files tagged, so we use a FileQuery. We could also get other items, such as mails (in Akonadi): in that case we could use a a Nepomuk.Query.Query():

        query = Nepomuk.Query.FileQuery(comparison_term)

Lastly, we want to get some results out of this query. There are different methods, but for this tutorial we’ll use the tried-and-tested KIO technology:

        search_url = query.toSearchUrl()
        search_job = KIO.listDir(kdecore.KUrl(search_url))
        search_job.entries.connect(self.search_slot)
        search_job.result.connect(search_job.entries.disconnect)

First we convert the query to a nepomuksearch:// url, which then we pass to KIO.listDir, to list the entries. Unlike my previous post on KIO, this job emits entries() every time one is found, so we connect the signal to our search_slot method. We also connect the job’s result() signal in a way that it will disconnect the job once it’s over.

Finally, let’s take a look at the search_slot function:

    def search_slot(self, job, data):

        # We may get invalid entries, so skip those
        if not data:
            return

        for item in data:
            print item.stringValue(KIO.UDSEntry.UDS_DISPLAY_NAME)

Entries are emitted as UDSEntries: to get something at least understandable, we turn them into the file name, which is obtained by the stringValue() call using KIO.UDSEntry.UDS_DISPLAY_NAME.

That’s it. As you can see, it was pretty easy. Of course there’s more than that. For further reading, take a look at Nepomuk’s Query API docs, and Query Examples. Bear in mind however that to the best of my knowledge, the “fancy operators” mentioned there will not work with Python.

Happy Nepomuk querying!

As most of KDE is C++, and the Python API docs are translated directly from the C++ API docs, it is essential to have good examples to help newcomers learn faster. There are some PyKDE4 examples in the kdebindings module already, but I put mine in kdeexamples for a number of reasons:

• Clear purpose: kdeexamples is meant exactly for this – example code;
• Visibility: A central place to find KDE examples even for bindings is optimal, makes easier to find what one is looking for.

Visibility is also important as currently the examples are rather buried inside kdebindings, and as far as I know they aren’t included in the packages of some distributions (at least not openSUSE; YMMV).

I decided to take this route because PyKDE4 is basically the job of one person (Simon Edwards): he does already a great job, but the work is too much for a single person to handle. And due to shortage of human resources, PyKDE4 lacks examples and documentation, and thus it’s not always easy to understand how to use the C++ API in Python. Writing snippets of working code, with extensive comments, is a step in the good direction. And also an opportunity to contribute back to KDE after all these years!

For now there’s just KConfigXT, but I plan on tackling KIO next, as soon as I have time. Of course, help is welcome!

Danbooru? Is it something you eat?

Well, aside from the Wikipedia link above, I think a small introduction is in order, at least for the readers coming from PlanetKDE. Danbooru is a kind of image board which structures its data semantically, by having tags attached to images (along with other things, such as favorites, rating, etc.). It can be browsed normally (newest posts, etc.) or by using tags and other properties. Some boards are quite popular in the anime-viewing community. The neat thing about Danbooru (which is by itself a Ruby on Rails application) is the fact that it can provide a REST and POST API to access data. So. it’s technically possible to access such boards programmatically: the API permits not only retrieving posts, but also upload, tag, and perform other operations.

The API could be technically used also for client applications, in order to free the user from using a browser. That is what Danbooru Client is aiming to do.

Introducing Danbooru Client

Danbooru Client fits exactly these needs by providing a GUI to (part of) the Danbooru API.

Features:

• Connect to any Danbooru board (three predefined)
• Download up to 100 images with selectable tags;
• Download or view images with the KDE preferred image viewer;
• Tag semantically the images using Nepomuk.

Requirements:

• PyQt (at least version 4.5)
• PyKDE4 (tested with PyKDE 4.3 only)
• (optional) Nepomuk
• Python (at least version 2.5)

Screenshots

(click to enlarge)

Download & Installation

You can obtain Danbooru Client from kde-apps.org. For the bleeding edge people (but are there such users for such an application?) there is a git repository set up at Gitorious. Once downloaded, you need to use CMake to install the files. Unfortunately due to the way CMake is set up, you’ll need the KDE development headers and a working C++ compiler, even though you won’t need them for the installation.

The installation process is very straightforward:

cd /path/to/source
mkdir build; cd build
cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ../
make # This just byte-compiles Python files
sudo make install

Then, just launch “danbooru_client”.

Known limitations

There are plenty for now, it’s just version 0.1:

• Zero documentation (although it’s kind of straightforward to use)
• Empty cells are created when a row is not filled with images
• No support for multi-download
• Untested login/password access
• The interface may be horrid
• Danbooru does not support rating filtering via API, so it’s not currently possible to do so

The client is licensed under the GPL v2 or later. The artwork for the splash screen is also under the GPL and was made by Melissa Adkins.

• KConfigXT requires an XML file and an INI-like file to be compiled by kconfig_compiler in order to produce C++ files
• There is no such a tool (at least to my knowledge) that does the same job for bindings

So what to do? Either give up on the niceness of KConfigXT, or work around the issue. I chose the latter.

Bypassing the kconfig_compiler limitation

What kconfig_compiler does is basically generate the KConfigSkeleton sublcass needed for KConfigXT. So, we can create our own subclass by hand: a little more work is involved but nothing too hard. The following snippets, taken from a GPL application I’m working on, will demonstrate how to do it.

from PyQt4.QtCore import *
from PyQt4.QtGui import *
from PyKDE4.kdeui import *

#UI stuff - see later
from ui_generalpage import Ui_GeneralPage

class Preferences(KConfigSkeleton):

    """Class to handle preferences."""

    def __init__(self, *args):
        super(Preferences, self).__init__(self, *args)
        self.setCurrentGroup("General")
        self._danbooru_boards_list = QStringList()
        self._danbooru_boards = self.addItemStringList("danbooruUrls",
                                                       self._danbooru_boards_list,
                                                       QStringList())

Here we set up a KConfigSKeleton subclass. The first thing we set up after that is the config group we want to use: we can have several, for example “General”, “Services”, and so on. Of course an empty group makes nothing, so we populate it, in this case with a QStringList configuration item (see the API docs (KCoreConfigSkeleton, but KConfigSkeleton is a subclass of that) for more types you can use). You’ll notice that we assign an empty QStringList to a variable, which is then used in the addItemStringList call later. That’s because KConfigSkeleton (in C++) wants a pointer to the type of content, and since in Python we don’t have pointers, we pass a reference (and by binding it to our class instance, we make sure it won’t be garbage-collected).

The addItemStringList (and other addItem*) methods use three parameters: a string with the name of the option (remember this!), the reference to the item, and a default value (in this case an empty QStringList).. Once we’ve set the options, we call readConfig() in the initializer to make sure the values are read from the config (or default values created).

I set all the attributes as “hidden” to prevent direct manipulation. To access them, I set up properties (following the example of minirok, another PyKDE4 application).

    @property
    def boards_list(self):
        return self._danbooru_boards.value()

As you can see, the value of the configuration items is accessed via the value() function. Once tihs is done, we’re done with regards to the KConfigSkeleton part.

KConfigDialog

Of course now we want to create the config dialog. We do so by subclassing KConfigDialog. First, though, we must create the page contents. We do so in Qt Designer. We first create a widget, and then we place our configuration widgets on it. It is essential that the widget that will store our configuration details have the name kcfg_CONFIGOPTION, where CONFIGOPTION is the name you specified as a string in the KConfigSkeleton initializer. Once done, we save the ui file, compile with pykdeuic4, we set it in the imports of our preferences file and we’re good to go.

The following is an example of a general configuration page widget (the UI_* is the pykdeuic4 generated file):

class GeneralPage(QWidget, Ui_GeneralPage):

    def __init__(self, parent=None, preferences=None):
        super(GeneralPage, self).__init__(parent)
        self.setupUi(self)

        self.kcfg_danbooruUrls.insertStringList(preferences.boards_list)

As you can see, we pass the preferences instance in the initializer, so we can populate the widgets (which are indeed named kcfg_danbooruUrls, just like the config option I set earlier) . Of course you can connect signals and whatnot to slots in case you want to do something with your widgets. I didn’t have the need, so no need to.

And once we have this set up, we can finally create the KConfigDialog!

class PreferencesDialog(KConfigDialog):

    def __init__(self, parent=None, name=None, preferences=None):
        super(PreferencesDialog, self).__init__(parent, name, preferences)

        self.setButtons(KDialog.ButtonCode(KDialog.Ok |KDialog.Apply |
                                            KDialog.Cancel))

        self.general_page = GeneralPage(self, preferences)
        self.general_page_item = self.addPage(self.general_page, 'General')

In the initializer, we pass the preferences instance, the name (used later to determine if a page is already open, since KConfigDialog is non-modal), and of course, the parent widget. We then set the buttons (using bitwise ORs) we want to show. Finally, we instantiate our page widget and add it to the dialog, specifying a name that will appear on the side. Using the setIcon method you can also set an icon for your page. In case you want to perform checks and other things, reimplement slotButtonClicked in your subclass with (self, button) as parameters. But dont’ forget to call the original KConfigDialog.slotButtonClicked(button) in that case.

Wrapping it up: calling KConfigDialog

Finally, how to call your dialog? First of all, you need to instantiate your preferences object, for example in your main window application code:

self.preferences=preferences.Preferences()

Then, in your code, you do something like this:

if KConfigDialog.showDialog("Preferences dialog"):
    return
else:
    dialog = preferences.PreferencesDialog(self, "Preferences dialog",
                                           self.preferences)
    dialog.show()

The first if ensures that if there is already one dialog open, it won’t open another. If that’s not the case, we instantiate the dialog, passing it the name (which must be the same as the if above), the parent, and the preferences instance.

Voila’. In the end, you’ll get something like this (slightly different):

I know my own UI sucks here, but it’s something I’m still experimenting…

For this tutorial, thanks go to Pino “pinotree” Toscano, who pointed me to the “minirok” project, which makes use of KConfigXT, and Adeodato Simò, the author of minirok.