Tutorial on writing Ubuntu Unity Lenses/Places in Python

Ubuntu Unity is a really cool and innovative approach for Ubuntu UI. There are many people who love it and many who hate it. I fall somewhere in the middle. I am really fascinated by the possibilities that Unity offers and hope that it becomes better as it matures. Lenses are one of the coolest pieces in Unity and unfortunately not much tutorial is written. So this is my stab to fill that void. I have tried to organize as many material as possible. Your comments on improving the article is always welcome !

In my tutorial on Unity , I mentioned that if no one else writes a Lens tutorial, I will write one and here it is 🙂 Lenses in Ubuntu are a really neat idea – One simplistic way is to view them as specialized search tools. You open the appropriate lens, type something and you get a list of results. But this explanation does not really do justice to the incredible amount of flexibility that they give. Lenses can group their results, have Unity render the results in different styles, have multiple sections that influence they way search is done and so on. Unity also provides a very powerful API that allows you to write literally anything that you can think of. This post will discuss the architecture, components and their potential capabilities in detail.

Ubuntu Lens Terminology

If you are using Unity, then you must be familiar with two default lens that come with it : Application lens and Files & Folders lens. Let me use that to explain the various parts of a Lens.

Places/Lenses : Both these words represent the same idea. Places is a terminology that was primarily used when Unity was introduced. Its usage is now slowly deprecated and the word Lenses is preferred. In the rest of this blog post, I will refer it as Lenses for uniformity. Let us take a look at the various parts of lens by taking the application lens as an example.

If you click on the Application lens, you can see that it is split into two important pieces. At the top, is a search textbox like entity that allows you to enter the query. At the bottom is the results pane that shows results of your query. At the left end of the search textbox is a search result indicator. When the search is still going on, the indicator will show a spinning circle. Once the search is done, it reverts to its default icon of a cross.

Sections : The simplest way to describe sections is that they behave like categories that are non overlapping. So if a given search query might result in different results when searched under different categories, each of the qualify as a section.

Consider a simple example – You are writing a lens for StackOverflow. You may want to search questions, tags, users and so on. The results of search query q as a question is not the same as when searching q as a tag. Hence questions, tags, users become sections. Unity allows you to easily have different sections and switch between them.

Sections are the entries in the dropdown list  at the right end of the search textbox. They are optional and many places need not have it. You can see all sections of a lens by clicking on the dropdown. Taking the example of Application lens, some of the sections are “All Applications”, “Accessories”, “Games”, “Graphics” etc.

Groups : Groups is a mechanism by which you can club certain search results under a meaningful entity. Each search result, might have one or more groups that allow you to organize the results. For eg, when you search in Application lens, the groups are “Most frequently used”, “Installed”, “Available for download” etc. Groups need not be non overlapping like sections. Given a search query, same result can occur in different groups. In addition, Unity allows you to have different icons for different groups. Also, each group can be rendered in a different style. I will discuss further details later in the blog post.

Difference between Sections and Groups : There are lot of differences between groups and sections. Sections are mostly non overlapping set of entries. Each section provides a different perspective of the same search query. In contrast, groups allow you to classify the search results from a query (and a section). Groups can be considered as a way to organize the results rather than influencing how the results are obtained (which the sections do).

Results : These are the output of a search query in a lens. Given a query and a section, you get a list of entries for results. Each of them can optionally be assigned to a group. Each result entry can display information about themselves in a concise way. In addition, Unity allows them to have any URI and a mime type. So the results of one lens might be files clicking which executes them. Or it can be results from web and clicking on them opens the link in a browser and so on. Unity also allows them to have custom icons.

Unity Lens – Technical Terminology

In the following section, we will discuss some terms used in Lens development.

DBUS : DBUS is one of the most important component in the development of lens. One way to view a lens is as a daemon that accepts a search query from Unity, does some processing and returns a result along with information on how to display them. DBUS is the conduit through which the entire communication between the daemon and Unity happens. For the purpose of the lens, you need to own a bus which will be used by Unity for communication.

Lens/Place Daemon : Lens/Place daemon is a program that exposes lens functionality. A single daemon can expose multiple lens functionalities. Each lens is identified by an entry. It accepts search string from Unity and sends out search results that annotated with group and other additional information.

Place File : A place file is how you inform Unity about the various lenses that your daemon is going to expose. It is a text file that ends with .place extension and usually placed in /usr/share/unity/places . It contains different groups of entries that describe the different lenses that are exposed.

Lens Entry : A lens or an entry in the place file is distinct entity that can accept a search query and provide appropriate results. Every place file contains atleast one lens entry. Every entry has a distinct location for itself in the Unity places bar (the vertical strip) on the left. The lens entry has 3 broad components : A model each for sections, groups and results. Results contain information about the groups they fall in and how to display themselves.

Results : As discussed above, a result is an entry that is the response to a query. A result can be assigned to one or more groups. In the most general sense, a result consists of 5 subparts :
(a) URI : This is a resource identifier to uniquely denote the location of search result. It can be a local item (file://) , web item (http://) and so on.
(b) Display Name : This is a name for the result that the user will see in the results pane.
(c) Comment : This is additional information about the result entry.
(d) MimeType : Since the URI can point to anything, it is important to inform Unity what action to perform when the user clicks on the result. The mimetype allows Unity to invoke the appropriate launcher.
(e) Icon : Each result can have its own icon to represent it visually. It can be an icon file or the generic name of the icon (eg video).

Renderer : Unity provides some flexibility in how the results are displayed. Each result falls into some group. We can request Unity to display each group in a specific way. This is accomplished by the use of renderers. When you setup the model for groups for the lens, we also specify how each group will be rendered. Some common renderers are :

(a) UnityDefaultRenderer : This is the default way to display the results. In this renderer, each result shows the icon and the display name beneath it.

(b) UnityHorizontalTileRenderer : In this renderer, the icon and display name for each result is shown. In addition, it also displays the comment associated with the result.

(c) UnityEmptySearchRenderer : This renderer is used when the current search query returned no results. The result item construction is very similar to the results above. But the display name is displayed across the results pane.

(d) UnityShowcaseRenderer : I tried using it and the result was not much different from UnityDefaultRenderer. But according to the documentation, it should have a bigger icon.

(e) UnityEmptySectionRenderer : I did not try this as it not make sense in the application I developed. Supposedly, it is used to imply that the current section is empty. If my interpretation is correct, then this is used when the current section returned no results for query but a different section might produce results. UnityEmptySearchRenderer on the other hand is used to imply that the current search query itself (regardless of the section) provides zero results.
(f) UnityFileInfoRenderer : Copying from the reference, this renderer is used in files place to show search results. Expects a valid URI, and will show extra information such as the parent folder and whatever data is in the comment column of the results.

Steps to write a Lens :

There are three major steps in writing a Lens.
(1) Writing a .place file
(2) Writing a Lens daemon
(3) If you want to distribute , Writing a service file

As an example, let us develop a Lens that does the following :
(1) It has two sections – In “Movie Names” section, only the names of the movie are shown. In “Genre” section, all movies are clubbed according to their genre which act as a groups. So if movie X is in genres Y and Z, X will be displayed in both groups Y and Z.
(2) Clicking on the result will open a browser and redirect to the IMDB page for the movie.
(3) The lens accepts queries from two places – When entered directly in the IMDB Lens and also from the dash. When searched from Dash , it will display movie names as a separate group.

At the initial state, the lens will look like this :

For the sake of completeness, here is now it looks when you just search for Movie Names.

For the sake of completeness, here is now it looks when you just search for Genres. Basically, the results are grouped using the Genre. If a movie falls under multiple genres, it also falls into different groups.

Let us take a look at how to write the IMDB lens as per the major steps above.

Writing a Place File :

As discussed above a place file contains the information that allows Unity to display the entries in the places bar. Information like which bus to use for communication, what shortcut to use etc are also involved. For the purpose of this tutorial, I will put up the place file I used for the IMDB lens. I will then explain the significance of each line. The file is named as imdbSearch.place and is placed in /usr/share/unity/places/ .

[Place]
DBusName=net.launchpad.IMDBSearchLens
DBusObjectPath=/net/launchpad/imdbsearchlens

[Entry:IMDBSearch]
DBusObjectPath=/net/launchpad/imdbsearchlens/mainentry
Icon=/usr/share/app-install/icons/totem.png
Name=IMDB Search
Description=Search Movies using IMDB
SearchHint=Seach Movies using IMDB
Shortcut=i
ShowGlobal=true
ShowEntry=true

[Desktop Entry]
X-Ubuntu-Gettext-Domain=imdbSearch-place

As you can see, the file has three sections. Each section contains a set of key-value pairs.

Place Section :
This is the simplest section and contains two key values – DBusName and DBusObjectPath. DBusName gives the name of the bus under which this entry can be found while DBusObjectPath provides the actual dbus object path. The names can be any valid DBus names.

Entry Section :
A place file can contain one or more entries. Each entry must contain a section that corresponds to it. Each entry will occupy a distinct location in the places bar. If there are multiple entries, each of them must have a unique name and object path. In the daemon code, all those entries must be added individually.

The various keys are :
DBusObjectPath : This is the DBus path used to communicate with this specific entry. Note that this path must be a child of mail DBusObjectPath. In our case, there is only one entry and hence we put it under the path “mainentry” of the original path.
Icon : Link to the icon file
Name : Name of the entry. When you hover over the entry in the places bar, this will be displayed.
Description : A long description of the lens. I am not sure where this is used.
SearchHint : This is the text that is displayed by default in the lens when the user selects it. In the image above, the search hint “Search Movies using IMDB”is displayed when the user selects the IMDB lens.
Shortcut : This gives the key which is used to trigger the lens. Of course, you can always use the mouse to select it. If this key is specified,then pressing Super+shortcut operns the lens. For the IMDB lens, pressing Super+i opens it.
ShowGlobal : This is an optional key and defaults to true. If it is set to false, then searches from the main dash are not sent to the lens. This seems to override the specification inside the lens daemon. ie If the place file specifies ShowGlobal as false and the daemon adds a listener to the event where user enters a query in the main dash, it is not invoked. Most of the time, I think it makes more sense for the lens to set this as false. For eg, it certainly does not make sense for IMDB lens to offer its service in the dash. Most of the time, when the user is searching in the dash, he is looking for some file or application. Polluting those results with IMDB results may not be wise. This is even more true if your lens takes a while to provide all the results.
ShowEntry : This is an optional key and defaults to true. If it is set to false, then the entry will not be displayed in the places bar. If this is set to false, then the Shortcut key becomes useless as well. Pressing the shortcut key does not invoke the lens. But if the ShowGlobal is set to true, then the lens will still be searchable via the dash. For eg, if for some reason, I decide that IMDB lens must only provide results to queries from dash I will set ShowGlobal to true and ShowEntry to false.

Desktop Entry Section :

This section is mostly optional. The most used key is that X-Ubuntu-Gettext-Domain. This key is used for internationalization purposes. If you want the lens should support internationalization, provide the appropriate entry name. If you are not familiar with internationalization in Ubuntu, there are two broad ways of achieving it : Either put all the translations statically in the file. Or put it in the appropriate .mo file which will then be put in some language-pack file. I included this line because Unity whines as “** Message: PlaceEntry Entry:IMDBSearch does not contain a translation gettext name: Key file does not have group ‘Desktop Entry'”.

Writing a Lens Daemon

The next step is to write a daemon that communicates with Unity over dbus path, does the search and returns annotated search results so that Unity can render them meaningfully. The daemon can be written in any language that support GObject introspection. Most common languages include C, Vala and Python. Vey informally, GOject is a mechanism by which bindings for other languages can be done relatively easily. The actual process needs multiple components. Based on the reference [2], this means that you must verify if the following packages are installed in the system – gir1.2-unity-3.0 , gir1.2-dee-0.5 and gir1.2-dbusmenu-glib-0.4 . Of course, the actual version numbers may change in the future. If installing does not make it work, look at the reference for additional instructions [2].

I will use the IMDB Search lens as an example to explain writing a lens daemon in Python. The full source code is in [1]. I will use snippets of the code to make the appropriate points. The first step is of course importing the appropriate libraries. If you see other Python lens file, they used to have a hack that probes Dee before importing Unity. In my tests I found it unnecessary. If you get some error in importing Unity, then take a look at other sample files [3] and do accordingly.

from gi.repository import GLib, GObject, Gio, Dee, Unity

The next step is to define the name of the bus that we will use to communicate with Unity. Note that this must exactly match the “DBusName” key in the place file.

BUS_NAME = "net.launchpad.IMDBSearchLens"

The next step is to define some constants for the sections in your lens. If your lens contain only one section, feel free to ignore the initial lines. Else define section constants appropriately. The only place where you will use these constants is to figure out which section the lens currently is in. The section ids are integers and are ordered from 0. Note that the order given here is the *exact* order in which the sections must be added to our lens in Unity.

Similarly, we can have constants for groups. Instead of creating lot of constants, I created the group ids dynamically. First, I create a list of all IMDB genres and use a hash to map the name to an integer (group id). Also note that I also have constants for groups – GROUP_EMPTY, GROUP_MOVIE_NAMES_ONLY and GROUP_OTHER.

One thing to notice is that if different sections have non overlapping groups, all of them must be defined here. Then based on current section, use the appropriate group. As an example, GROUP_MOVIE_NAMES_ONLY is used only with SECTION_NAME_ONLY. But we define it alongside other groups. Also note the group for empty, GROUP_EMPTY. This will be used if the search query returns no results.  As with sections, the order of groups defined here must exactly match the order in which they are added to group model. If you have reasonably small number of sections and groups, you can avoid the elaborate setup of writing constants.

SECTION_NAME_ONLY = 0
SECTION_GENRE_INFO = 1

allGenreGroupNames = [ "Action", "Adventure", "Animation", "Biography", "Comedy", "Crime", "Documentary", "Drama", "Family",    "Fantasy", "Film-Noir", "Game-Show", "History", "Horror", "Music",  "Musical", "Mystery", "News", "Reality-TV", "Romance", "Sci-Fi", "Sport", "Talk-Show", "Thriller", "War", "Western"]

numGenreGroups = len(allGenreGroupNames)
GROUP_EMPTY = numGenreGroups
GROUP_MOVIE_NAMES_ONLY = numGenreGroups + 1
GROUP_OTHER = numGenreGroups + 2

groupNameTogroupId = {}
#We create a hash which allows to find the group name from genre.
for i in range(len(allGenreGroupNames)):
        groupName = allGenreGroupNames[i]
        groupID = i
        groupNameTogroupId[groupName] = groupID

The next step is to define the skeleton of the lens daemon. It is a simple Python class. In the constructor, you define the entire model corresponding to each entry in the Lens. If you place file contains n entries, you will be defining n different PlaceEntryInfo. In our case we have only one. Hence we create a variable that points to the corresponding DBusObjectPath. It is impertative that the path exactly match DBusObjectPath of the entry.

Each PlaceEntryInfo consists of different models : sections_model, groups_model and results_model.  If you want the lens to respond to searches in dash, you will also need to setup global_groups_model and global_results_model . The code below contains information about the schema of the different models. You can consider them as more or less a code that can be blindly copied. If you want additional information about things that you can tweak in PlaceEntryInfo, take a look this url .

Note on Property based access :
One important thing to notice is that all the access is done using properties. There are two methods to do that :
(1) x.props.y
(2) x.get_property(“y”)

Choosing one of them is mostly based on your coding style. Choose one use it consistently.

class Daemon:
        def __init__ (self):
                self._entry = Unity.PlaceEntryInfo.new ("/net/launchpad/imdbsearchlens/mainentry")

                #set_schema("s","s") corresponds to display name for section , the icon used to display
                sections_model = Dee.SharedModel.new (BUS_NAME + ".SectionsModel");
                sections_model.set_schema ("s", "s");
                self._entry.props.sections_model = sections_model

                #set_schema("s","s") corresponds to renderer used to display group, display name for group , the icon used to display
                groups_model = Dee.SharedModel.new (BUS_NAME + ".GroupsModel");
                groups_model.set_schema ("s", "s", "s");
                self._entry.props.entry_renderer_info.props.groups_model = groups_model

                #Same as above
                global_groups_model = Dee.SharedModel.new (BUS_NAME + ".GlobalGroupsModel");
                global_groups_model.set_schema ("s", "s", "s");
                self._entry.props.global_renderer_info.props.groups_model = global_groups_model

                #set_schema(s,s,u,s,s,s) corresponds to URI, Icon name, Group id, MIME type, display name for entry, comment
                results_model = Dee.SharedModel.new (BUS_NAME + ".ResultsModel");
                results_model.set_schema ("s", "s", "u", "s", "s", "s");
                self._entry.props.entry_renderer_info.props.results_model = results_model

                #Same as above
                global_results_model = Dee.SharedModel.new (BUS_NAME + ".GlobalResultsModel");
                global_results_model.set_schema ("s", "s", "u", "s", "s", "s");
                self._entry.props.global_renderer_info.props.results_model = global_results_model

Once you have setup the models, you need to add listeners to events that you want to catch. The most important one is “notify::synchronized”. This called when Unity sets up your lens and wants to know the various groups and sections in your entry. In the code below, we add three different functions to that event. One gives the sections in the lens, other gives the groups and last gives the groups in dash.

Next we catch two events that are core to Lens – notify::active-search and notify::active-global-search . The first is triggered when the user searches something in the search textbox of the place while the second is triggered when user searches something in the dash. It is important to notice that the same search can trigger the events multiple times. By default, Unity does a decent job of batching calls providing search strings, but it is an important thing to consider if your lens does expensive operations. Take a look at the section of caching for additional details.

The event notify::active-section is triggered when the user changes the section of the lens by using the dropdown. You can then use your section constants to decide which section is currently selected.

notify::active is triggered when the user selects and leaves your place. Hence its an indirect way for your daemon to know if the lens is being visible to the user.

                # Populate the sections and groups once we are in sync with Unity
                sections_model.connect ("notify::synchronized", self._on_sections_synchronized)
                groups_model.connect ("notify::synchronized", self._on_groups_synchronized)

                #Comment the next line if you do not want your lens to be searched in dash
                global_groups_model.connect ("notify::synchronized", self._on_global_groups_synchronized)

                # Set up the signals we'll receive when Unity starts to talk to us

                # The 'active-search' property is changed when the users searches within this particular place
                self._entry.connect ("notify::active-search", self._on_search_changed)

                # The 'active-global-search' property is changed when the users searches from the Dash aka Home Screen
                #       Every place can provide results for the search query.

                #Comment the next line if you do not want your lens to be searched in dash
                self._entry.connect ("notify::active-global-search", self._on_global_search_changed)

                # Listen for changes to the section.
                self._entry.connect("notify::active-section", self._on_section_change)

                # Listen for changes to the status - Is our place active or hidden?
                self._entry.connect("notify::active", self._on_active_change)

Once you have set up the different models and functions to populate them, you need to add the entry to a PlaceController. If your lens has multiple entries, repeat the above process for each entry and once constructed call the add_entry of PlaceController to set them up. Note that the argument to PlaceController’s constructor is same as the DBusObjectPath for the Place section in your .place file.

                self._ctrl = Unity.PlaceController.new ("/net/launchpad/imdbsearchlens")
                self._ctrl.add_entry (self._entry)
                self._ctrl.export ()

Once we have setup all the models, the next step is to define the functions that are used.The first is to define the function that populates the entry’s section model. Note that we call append on the sections_model with two parameters : the name of the genre and an icon for it. You can also observe that when defined the “schema” of the sections_model, it accepted two strings. One other thing to note is the lack of use of any section constants – You must be careful to define the sections in the exact same order as the constants. In our case, it means that SECTION_NAME_ONLY followed by SECTION_GENRE_INFO.

        def _on_sections_synchronized (self, sections_model, *args):
                # Column0: display name
                # Column1: GIcon in string format. Or you can pass entire path (or use GIcon).
                sections_model.clear ()
                sections_model.append ("Movie Names", Gio.ThemedIcon.new ("video").to_string())
                sections_model.append ("Movie Genre", Gio.ThemedIcon.new ("video").to_string())

The next step is to define a set of groups. Due to the nature of this lens, we reuse the list to form it. Notice the use of UnityEmptySearchRenderer for the GROUP_EMPTY. For this example, I have used UnityHorizontalTileRenderer. Your lens might need some other renderer – Take a look at the renderer section above for a discussion of the different renderers.

                # Column0: group renderer, # Column1: display name, # Column2: GIcon in string format Or you can pass entire path (or use GIcon).
                groups_model.clear ()

                #Remember to add groups in the order you defined above (ie when defining constants)
                for groupName in allGenreGroupNames:
                        groups_model.append ("UnityHorizontalTileRenderer", groupName, Gio.ThemedIcon.new ("sound").to_string())
                #GROUP_EMPTY
                groups_model.append ("UnityEmptySearchRenderer", "No results found from IMDB", Gio.ThemedIcon.new ("sound").to_string())
                #GROUP_MOVIE_NAMES_ONLY
                groups_model.append ("UnityHorizontalTileRenderer", "Movie Names", Gio.ThemedIcon.new ("sound").to_string())
                #GROUP_OTHER
                groups_model.append ("UnityHorizontalTileRenderer", "Other", Gio.ThemedIcon.new ("sound").to_string())

The next step is to define the function that is called when the search changes in the place search box. Notice how we use the entry object to get the current section, the current results, current search query and so on. Finally, we invoke search_finished function which calls search.finished() which signals to Unity that we are done processing the query.

        def _on_search_changed (self, *args):
                entry = self._entry
                self.active_section = entry.get_property("active-section")
                search = self.get_search_string()
                results = self._entry.props.entry_renderer_info.props.results_model
                print "Search changed to: '%s'" % search
                self._update_results_model (search, results)
                #Signal completion of search
                self.search_finished()

There are other functions which we can detail. But mostly, they are very similar to code shown here. You can take a look at the python file linked below [1] for full glory.

So far all we have done is using some boilerplate code. From now on though, the code starts to differ based on the application. So I have not included the code that actually produces the results here. Take a look at the python file for details.

Testing Instructions

Once you have written the python file , you want to test your baby. Here are the steps :

(1) Include the following code in your daemon. This code was literaly copied from Unity Sample Place [3] code.

if __name__ == "__main__":
        session_bus_connection = Gio.bus_get_sync (Gio.BusType.SESSION, None)
        session_bus = Gio.DBusProxy.new_sync (session_bus_connection, 0, None, 'org.freedesktop.DBus', '/org/freedesktop/DBus', 'org.freedesktop.DBus', None)
        result = session_bus.call_sync('RequestName', GLib.Variant ("(su)", (BUS_NAME, 0x4)), 0, -1, None)

        # Unpack variant response with signature "(u)". 1 means we got it.
        result = result.unpack()[0]

        if result != 1 :
                print >> sys.stderr, "Failed to own name %s. Bailing out." % BUS_NAME
                raise SystemExit (1)

        daemon = Daemon()
        GObject.MainLoop().run()

(2) Copy your place file to /usr/share/unity/places/ . If you have any custom icons, copy them to the location specified in your .place file.
(3) Open up a new terminal and invoke your daemon file. Also remember to set the executable bit on.
(4) Open up another terminal and type “setsid unity”. Using setsid is a very neat trick I learnt from the sample place file. Basically, it starts Unity in a new session. This forces it to read all the place files again. Also if you make any change to the daemon code, you can kill it and restart it. Unity will start communicating with your new daemon. Additionally, setsid will also ensure that Unity does not have controlling terminal but will still dump all debug information in the terminal it was opened.
(5) Open the lens and type your query and watch the results appear !

Debugging Checklist

If your lens is not working as expected, here are somethings to verify :

(1) Make sure that your place file is copied to /usr/share/unity/places .
(2) Make sure that busname and object path match exactly in your place file and your daemon file.
(3) Make sure that Python file has its executable bit on. This is important if you want to run it a service/daemon that runs automatically. More on that below.
(4) If you are simply testing it, then is your Daemon file running ? If you are running it as a service, is your service file contain information that match your place and daemon file ?
(5) Did you restart Unity  – preferably as “setsid unity”
(6) Did you make any recent changes to place file ? If so make sure it is copied and restart Unity.
(7) Check for any exception information in the terminal that you started your daemon. If its a service, enable logging and examing the log files.
(8) Check if your lens is actually started. If you used “setsid unity” in a terminal, it would be logging the various steps it does. One sample invocation showing successful starting of lenses is this :

    ** (<unknown>:6114): DEBUG: PlaceEntry: Applications
** (<unknown>:6114): DEBUG: PlaceEntry: Commands
** (<unknown>:6114): DEBUG: PlaceEntry: Files & Folders
** (<unknown>:6114): DEBUG: PlaceEntry: IMDB Search
** (<unknown>:6114): DEBUG: /com/canonical/unity/ applicationsplace
** (<unknown>:6114): DEBUG: /com/canonical/unity/filesplace
** (<unknown>:6114): DEBUG: /net/launchpad/imdbsearchlens

(9) If your lens works but puts results in strange groups, make sure that order of groups in synchronize and the constants are same.
(10) Common errors and fixes :

** Message: PlaceEntry Entry:IMDBSearch does not contain a translation gettext name: Key file does not have group ‘Desktop Entry’ :

This is not an error. If this annoys you add a [Desktop Entry] section. See above for details.

** (<unknown>:6114): WARNING **: Unable to connect to PlaceEntryRemote net.launchpad.IMDBSearchLens: No name owner

This is again not an error but indicates that either your daemon program is not running or is not able to own the bus specified in the .place file.

Installation Instructions

Since I primarily wrote the IMDB lens for learning Unity, I do not know much about the actual installation process. Here are some generic tips :

(1) If you want a simple method of installation, use distutils. It accepts a list of files and the location where they must be copied. This is the cleanest way.
(2) If you are going to install it and expect the lens to start automatically, then you should write a .service file that knows which bus start and which file to invoke to make that happen. The service file is usually put in “/usr/share/dbus-1/services/” . In this case, also make sure that the daemon file is actually executable !

[D-BUS Service]
Name=net.launchpad.IMDBSearchLens
Exec=/path/to/daemom/file

Various Tips On Writing Lenses

(1) Most of the simple daemons use constants for sections and groups. If you want them to setup them up dynamically, take a look how it is done in the IMDB lens.
(2) Avoiding repeated searches :
When the user enters a query in the lens, it is not necessary that the search function will be called only once. Remember that there is no concept of return key to indicate that query is complete. In fact, if the user presses the return key, it selects (and opens) the first result. The way Unity handles this scenario is by batching the calls. Lets say the user wants to search “blah blah2”. If the user continuously types the query with minimal interruption of the keyword, then the entire query will be sent to lens in one shot. On the other hand, if the user is a slow typer and enters “blah b” before waiting for a second or so, Unity will call the search function with partial query. When the user completes the query , the lens will be called with the entire query.

This behavior complicates your lens behavior, especially if the processing is time consuming. There are different techniques to avoid running calculations repeatedly (IMDB lens uses the first two techniques):
(a) Have a cutoff : Your code might decide not to search if the length of string is less that say 4 characters.
(b) Have a cache with timeout : You can use a local cache that stores your previous results . When you get a new query, check your cache first and return the results from it. For added benefit, have a cache timeout that removes elements that were added long time ago.
(c) Memoize using functools : A very cool technique that is used in other lenses is to memoize the function call. This technique works if the function is reasonably simple – the key is the function argument and the value is the return value of the function. One simple example is shown below. In the example, we defined a decorator called memoize_infinitely and apply it to function foo. Foo accepts an input and returns an output. This decorator, automagically creates a cache for each function. When the function is called with some argument, it is first checked in the cache. If it is found, then it is returned without invoking the function. Else the function is called and the result is stored in the cache. This technique is widely used. For a specific example,take a look at the AskUbuntu lens [3] .

import functools
def memoize_infinitely(function):
    cache = {}
    @functools.wraps(function)
    def wrapped(*args):
        if not args in cache:
            cache[args] = function(*args)
        return cache[args]
    return wrapped

@memoize_infinitely
def foo(input):
	return input + 1

(3) Handling long computations :
If your lens returns lot of results or the processing for each result entry takes a lot of time, then its a good idea to display the information as it arrives. The results model has a function called flush_revision_queue which periodically sends the data so far to Unity. For eg, in the case of IMDB lens , fetching the genre information is expensive. So, the code flushes the results every time five movies were processed. This allows the user to see some results without waiting for eternity to get complete results.

Links

    [1] The code for IMDB lens which I have tried to comment as much as possible is my github page. For convenience, I have also given the individual files : Readme, imdb-search.py, imdbSearch.place .

    [2] Unity Places – now with 100% More Python : This blog post contains a brief discussion on developing Unity lenses in Python. It has some info on installation and links to a sample lens in Python. I would advise you to start with the sample lens code given in this blog post before making drastic changes. This way you can make sure that the initial lens setup is fine and the issue is really in your code 🙂
[3] Link to some Good Unity Python Lens codes : As of now there are few other good Unity lenses written in Python. Here are some of  my favorites – AskUbuntu lens, Launchpad lens, Evernote lens, Book-Search lens, Music search lens , Spotify lens . I have tried to incorporate all cool features in IMDB Search lens , so that it will become a one stop place for most important Lens features 🙂

    [4] Ubuntu Unity Architecture : This contains some language independent discussion of Unity architecture and additional information of the data structure it uses.
[4] IMDbPy : The IMDB search lens was developed using the excellent IMDbPy library. It has very convenient API that allows development of IMDB based applications a snap.

  [5] Ubuntu Unity Lens Python API Links : Here are some links for documentation that I found  – Dee API, Unity API . The document for Unity also encompasses the documentation for Places.

Advertisement