Zeitgeist Client API

ZeitgeistClient

class zeitgeist.client.ZeitgeistClient

Convenience APIs to have a Pythonic way to call and monitor the running Zeitgeist engine. For raw DBus access use the ZeitgeistDBusInterface class.

Note that this class only does asynchronous DBus calls. This is almost always the right thing to do. If you really want to do synchronous DBus calls use the raw DBus API found in the ZeitgeistDBusInterface class.

delete_events(event_ids, reply_handler=None, error_handler=None)

Warning: This API is EXPERIMENTAL and is not fully supported yet.

Delete a collection of events from the zeitgeist log given their event ids.

The deletion will be done asynchronously, and this method returns immediately. To check whether the deletions went well supply the reply_handler and/or error_handler funtions. The reply handler should not take any argument. The error handler must take a single argument - being the error.

With custom handlers any errors will be printed to stderr.

In order to use this method there needs to be a mainloop runnning.

find_event_ids_for_template(event_template, ids_reply_handler, **kwargs)

Alias for find_event_ids_for_templates(), for use when only one template is needed.

find_event_ids_for_templates(event_templates, ids_reply_handler, timerange=None, storage_state=2, num_events=20, result_type=0, error_handler=None)

Send a query matching a collection of Event templates to the Zeitgeist event log. The query will match if an event matches any of the templates. If an event template has more than one subject the query will match if any one of the subject templates match.

The query will be done via an asynchronous DBus call and this method will return immediately. The return value will be passed to ‘ids_reply_handler’ as a list of integer event ids. This list must be the sole argument for the callback.

The actual Events can be looked up via the get_events() method.

This method is intended for queries potentially returning a large result set. It is especially useful in cases where only a portion of the results are to be displayed at the same time (eg., by using paging or dynamic scrollbars), as by holding a list of IDs you keep a stable ordering, and you can ask for the details associated to them in batches, when you need them. For queries with a small amount of results, or where you need the information about all results at once no matter how many of them there are, see find_events_for_templates().

In case of errors a message will be printed on stderr, and an empty result passed to ids_reply_handler. To override this default set the error_handler named argument to a callable that takes a single exception as its sole argument.

In order to use this method there needs to be a mainloop runnning. Both Qt and GLib mainloops are supported.

Parameters:

• event_templates – List or tuple of Event instances
• ids_reply_handler – Callable taking a list of integers
• timerange – A TimeRange instance that the events must have occured within. Defaults to TimeRange.until_now().
• storage_state – A value from the StorageState enumeration. Defaults to StorageState.Any
• num_events – The number of events to return; default is 20
• result_type – A value from the ResultType enumeration. Defaults to ResultType.MostRecentEvent
• error_handler – Callback to catch error messages. Read about the default behaviour above

find_event_ids_for_values(ids_reply_handler, **kwargs)

Alias for find_event_ids_for_templates(), for when only one template is needed. Instead of taking an already created template, like find_event_ids_for_template(), this method will construct the template from the parameters it gets. The allowed keywords are the same as the ones allowed by Event.new_for_values().

find_events_for_template(event_template, events_reply_handler, **kwargs)

Alias for find_events_for_templates(), for use when only one template is needed.

find_events_for_templates(event_templates, events_reply_handler, timerange=None, storage_state=2, num_events=20, result_type=0, error_handler=None)

Send a query matching a collection of Event templates to the Zeitgeist event log. The query will match if an event matches any of the templates. If an event template has more than one subject the query will match if any one of the subject templates match.

The query will be done via an asynchronous DBus call and this method will return immediately. The return value will be passed to ‘events_reply_handler’ as a list of :class:`Event`s. This list must be the sole argument for the callback.

If you need to do a query yielding a large (or unpredictable) result set and you only want to show some of the results at the same time (eg., by paging them), consider using find_event_ids_for_templates().

In case of errors a message will be printed on stderr, and an empty result passed to events_reply_handler. To override this default set the error_handler named argument to a callable that takes a single exception as its sole argument.

In order to use this method there needs to be a mainloop runnning. Both Qt and GLib mainloops are supported.

Parameters:

• event_templates – List or tuple of Event instances
• events_reply_handler – Callable taking a list of integers
• timerange – A TimeRange instance that the events must have occured within. Defaults to TimeRange.until_now().
• storage_state – A value from the StorageState enumeration. Defaults to StorageState.Any
• num_events – The number of events to return; default is 20
• result_type – A value from the ResultType enumeration. Defaults to ResultType.MostRecentEvent
• error_handler – Callback to catch error messages. Read about the default behaviour above

find_events_for_values(events_reply_handler, **kwargs)

Alias for find_events_for_templates(), for when only one template is needed. Instead of taking an already created template, like find_event_ids_for_template(), this method will construct the template from the parameters it gets. The allowed keywords are the same as the ones allowed by Event.new_for_values().

find_related_uris_for_events(event_templates, uris_reply_handler, error_handler=None, time_range=None, result_event_templates=[], storage_state=2, num_events=10, result_type=0)

Warning: This API is EXPERIMENTAL and is not fully supported yet.

Get a list of URIs of subjects which frequently occur together with events matching event_templates. Possibly restricting to time_range or to URIs that occur as subject of events matching result_event_templates.

Parameters:

• event_templates – Templates for events that you want to find URIs that relate to
• uris_reply_handler – A callback that takes a list of strings with the URIs of the subjects related to the requested events
• time_range – A TimeRange to restrict to
• result_event_templates – The related URIs must occur as subjects of events matching these templates
• storage_state – The returned URIs must have this storage state
• num_events – number of related uris you want to have returned
• result_type – sorting of the results by 0 for relevancy 1 for recency
• error_handler – An optional callback in case of errors. Must take a single argument being the error raised by the server. The default behaviour in case of errors is to call uris_reply_handler with an empty list and print an error message on standard error.

find_related_uris_for_uris(subject_uris, uris_reply_handler, time_range=None, result_event_templates=[], storage_state=2, num_events=10, result_type=0, error_handler=None)

Warning: This API is EXPERIMENTAL and is not fully supported yet.

Same as find_related_uris_for_events(), but taking a list of subject URIs instead of event templates.

static get_event_and_extra_arguments(arguments)

some methods of ZeitgeistClient take a variable number of arguments, where one part of the arguments are used to build one Event instance and the other part is forwarded to another method. This function returns an event and the remaining arguments.

get_events(event_ids, events_reply_handler, error_handler=None)

Look up a collection of Events in the Zeitgeist event log given a collection of event ids. This is useful for looking up the event data for events found with the find_event_ids_* family of functions.

Each event which is not found in the event log is represented by None in the resulting collection.

The query will be done via an asynchronous DBus call and this method will return immediately. The returned events will be passed to events_reply_handler as a list of Events, which must be the only argument of the function.

In case of errors a message will be printed on stderr, and an empty result passed to events_reply_handler. To override this default set the error_handler named argument to a callable that takes a single exception as its sole argument.

In order to use this method there needs to be a mainloop runnning. Both Qt and GLib mainloops are supported.

insert_event(event, ids_reply_handler=None, error_handler=None)

Send an event to the Zeitgeist event log. The ‘event’ parameter must be an instance of the Event class.

The insertion will be done via an asynchronous DBus call and this method will return immediately. This means that the Zeitgeist engine will most likely not have inserted the event when this method returns. There will be a short delay.

If the ids_reply_handler argument is set to a callable it will be invoked with a list containing the ids of the inserted events when they have been registered in Zeitgeist.

In case of errors a message will be printed on stderr, and an empty result passed to ids_reply_handler (if set). To override this default set the error_handler named argument to a callable that takes a single exception as its sole argument.

In order to use this method there needs to be a mainloop runnning. Both Qt and GLib mainloops are supported.

insert_event_for_values(**values)

Send an event to the Zeitgeist event log. The keyword arguments must match those as provided to Event.new_for_values().

The insertion will be done via an asynchronous DBus call and this method will return immediately. This means that the Zeitgeist engine will most likely not have inserted the event when this method returns. There will be a short delay.

If the ids_reply_handler argument is set to a callable it will be invoked with a list containing the ids of the inserted events when they have been registered in Zeitgeist.

In case of errors a message will be printed on stderr, and an empty result passed to ids_reply_handler (if set). To override this default set the error_handler named argument to a callable that takes a single exception as its sole argument.

In order to use this method there needs to be a mainloop runnning. Both Qt and GLib mainloops are supported.

insert_events(events, ids_reply_handler=None, error_handler=None)

Send a collection of events to the Zeitgeist event log. The events parameter must be a list or tuple containing only members of of type Event.

The insertion will be done via an asynchronous DBus call and this method will return immediately. This means that the Zeitgeist engine will most likely not have inserted the events when this method returns. There will be a short delay.

In case of errors a message will be printed on stderr, and an empty result passed to ids_reply_handler (if set). To override this default set the error_handler named argument to a callable that takes a single exception as its sole argument.

In order to use this method there needs to be a mainloop runnning. Both Qt and GLib mainloops are supported.

install_monitor(time_range, event_templates, notify_insert_handler, notify_delete_handler, monitor_path=None)

Install a monitor in the Zeitgeist engine that calls back when events matching event_templates are logged. The matching is done exactly as in the find_* family of methods and in Event.matches_template. Furthermore matched events must also have timestamps lying in time_range.

To remove a monitor call remove_monitor() on the returned Monitor instance.

The notify_insert_handler will be called when events matching the monitor are inserted into the log. The notify_delete_handler function will be called when events lying within the monitored time range are deleted.

Parameters:

• time_range – A TimeRange that matched events must lie within. To obtain a time range from now and indefinitely into the future use TimeRange.from_now()
• event_templates – The event templates to look for
• notify_insert_handler – Callback for receiving notifications about insertions of matching events. The callback should take a TimeRange as first parameter and a list of Events as the second parameter. The time range will cover the minimum and maximum timestamps of the inserted events
• notify_delete_handler – Callback for receiving notifications about deletions of events in the monitored time range. The callback should take a TimeRange as first parameter and a list of event ids as the second parameter. Note that an event id is simply an unsigned integer.
• monitor_path – Optional argument specifying the DBus path to install the client side monitor object on. If none is provided the client will provide one for you namespaced under /org/gnome/zeitgeist/monitor/*

Returns:

a Monitor

register_data_source(unique_id, name, description, event_templates, enabled_callback=None)

Register a data-source as currently running. If the data-source was already in the database, its metadata (name, description and event_templates) are updated.

If the data-source registry isn’t enabled, do nothing.

The optional event_templates is purely informational and serves to let data-source management applications and other data-sources know what sort of information you log.

Parameters:

• unique_id – unique ASCII string identifying the data-source
• name – data-source name (may be translated)
• description – data-source description (may be translated)
• event_templates – list of Event templates.
• enabled_callback – method to call as response with the `enabled’ status of the data-source, and after that every time said status is toggled. See set_data_source_enabled_callback() for more information.

register_event_subclass(event_type)

Register a subclass of Event with this ZeiteistClient instance. When data received over D-Bus is instantiated into an Event object, the provided subclass will be used.

register_subject_subclass(subject_type)

Register a subclass of Subject with this ZeiteistClient instance. When data received over D-Bus is instantiated into a Subject object, the provided subclass will be used.

Note that this method works by changing the Event type associated with this ZeitgeistClient instance, so it should always be called after any register_event_subclass calls.

Even better, if you also have a custom Event subclass, you may directly override the Subject type by changing its _subject_type class variable.

remove_monitor(monitor, monitor_removed_handler=None)

Remove a Monitor installed with install_monitor()

Parameters:

• monitor – Monitor to remove. Either as a Monitor instance or a DBus object path to the monitor either as a string or dbus.ObjectPath
• monitor_removed_handler – A callback function taking one integer argument. 1 on success, 0 on failure.

set_data_source_enabled_callback(unique_id, enabled_callback)

This method may only be used after having registered the given unique_id with register_data_source before.

It registers a method to be called whenever the `enabled’ status of the previously registered data-source changes.

Remember that on some systems the DataSourceRegistry extension may be disabled, in which case this method will have no effect.