Zeitgeist Documentation

Data Model

Event

class zeitgeist.datamodel.Event(struct=None)

Core data structure in the Zeitgeist framework. It is an optimized and convenient representation of an event.

This class is designed so that you can pass it directly over DBus using the Python DBus bindings. It will automagically be marshalled with the signature a(asaasay).

This class does integer based lookups everywhere and can wrap any conformant data structure without the need for marshalling back and forth between DBus wire format. These two properties makes it highly efficient and is recommended for use everywhere.

actor
Read/write property defining the application or entity responsible for emitting the event. Applications should us the filename of their .desktop file without the .desktop extension as their identifiers. Eg. gedit, firefox, etc.
append_subject(subject=None)
Append a new empty Subject and return a reference to it
id
Read only property containing the the event id if the event has one
interpretation
Read/write property defining the interpretation type of the event
manifestation
Read/write property defining the manifestation type of the event
matches_template(event_template)

Return True if this event matches event_template. The matching is done where unset fields in the template is interpreted as wild cards. If the template has more than one subject, this event matches if at least one of the subjects on this event matches any single one of the subjects on the template.

Basically this method mimics the matching behaviour found in the FindEventIds() method on the Zeitgeist engine.

static new_for_data(event_data)
Create a new Event setting event_data as the backing array behind the event metadata. The contents of the array must contain the event metadata at the positions defined by the Event.Fields enumeration.
static new_for_values(**values)

Create a new Event instance from a collection of keyword arguments.

Parameters:
  • timestamp – Event timestamp in milliseconds since the Unix Epoch
  • interpretaion – The Interpretation type of the event
  • manifestation – Manifestation type of the event
  • actor – The actor (application) that triggered the event
  • subjects – A list of Subject instances

Instead of setting the subjects argument one may use a more convenient approach for events that have exactly one Subject. Namely by using the subject_* keys - mapping directly to their counterparts in Subject.new_for_values():

Parameters:
  • subject_uri
  • subject_interpretation
  • subject_manifestation
  • subject_origin
  • subject_mimetype
  • subject_text
  • subject_storage
payload
Free form attachment for the event. Transfered over DBus as an array of bytes
subjects
Read/write property with a list of Subjects
timestamp
Read/write property with the event timestamp defined as milliseconds since the Epoch. By default it is set to the moment of instance creation

Subject

class zeitgeist.datamodel.Subject(data=None)

Represents a subject of an Event. This class is both used to represent actual subjects, but also create subject templates to match other subjects against.

Applications should normally use the method new_for_values() to create new subjects.

interpretation
Read/write property defining the interpretation type of the subject
manifestation
Read/write property defining the manifestation type of the subject
matches_template(subject_template)

Return True if this Subject matches subject_template. Empty fields in the template are treated as wildcards.

See also Event.matches_template()

mimetype
Read/write property containing the mimetype of the subject (encoded as a string) if applicable
static new_for_values(**values)

Create a new Subject instance and set its properties according to the keyword arguments passed to this method.

Parameters:
  • uri – The URI of the subject. Eg. file:///tmp/ratpie.txt
  • interpretation – The interpretation type of the subject, given either as a string URI or as a Interpretation instance
  • manifestation – The manifestation type of the subject, given either as a string URI or as a Manifestation instance
  • origin – The URI of the location where subject resides or can be said to originate from
  • mimetype – The mimetype of the subject encoded as a string, if applicable. Eg. text/plain.
  • text – Free form textual annotation of the subject.
  • storage – String identifier for the storage medium of the subject. This should be the UUID of the disk partition or the string inet for general resources on the internet or other items requiring connectivity.
origin
Read/write property with the URI of the location where the subject resides or where it can be said to originate from
storage
Read/write property with a string id of the storage medium where the subject is stored. Fx. the UUID of the disk partition or just the string inet for items requiring general connectivity to be available
text
Read/write property with a free form textual annotation of the subject
uri
Read/write property with the URI of the subject encoded as a string

Interpretation

In general terms the interpretation of an event or subject is an abstract description of “what happened” or “what is this”.

Each interpretation type is uniquely identified by a URI.

class zeitgeist.datamodel.Interpretation(uri, display_name=None, name=None, doc=None)

Manifestation

The manifestation type of an event or subject is an abstract classification of “how did this happen” or “how does this item exist”.

Each manifestation type s uniquely identified by a URI.

class zeitgeist.datamodel.Manifestation(uri, display_name=None, name=None, doc=None)

TimeRange

class zeitgeist.datamodel.TimeRange(begin, end)

A class that represents a time range with a beginning and an end. The timestamps used are integers representing milliseconds since the Epoch.

By design this class will be automatically transformed to the DBus type (xx).

begin
The begining timestamp of this time range
end
The end timestamp of this time range
static until_now()
Return a TimeRange from 0 to the instant of invocation

ResultType

class zeitgeist.datamodel.ResultType

An enumeration class used to define how query results should be returned from the Zeitgeist engine.

This class has the following members:

  • 0 - MostRecentEvents

    All events with the most recent events first

  • 1 - LeastRecentEvents

    All events with the oldest ones first

  • 2 - MostRecentSubjects

    One event for each subject only, ordered with the most recent events first

  • 3 - LeastRecentSubjects

    One event for each subject only, ordered with oldest events first

  • 4 - MostPopularSubjects

    One event for each subject only, ordered by the popularity of the subject

  • 5 - LeastPopularSubjects

    One event for each subject only, ordered ascendently by popularity

StorageState

class zeitgeist.datamodel.StorageState

Enumeration class defining the possible values for the storage state of an event subject.

The StorageState enumeration can be used to control whether or not matched events must have their subjects available to the user. Fx. not including deleted files, files on unplugged USB drives, files available only when a network is available etc.

This class has the following members:

  • 0 - NotAvailable

    The storage medium of the events subjects must not be available to the user

  • 1 - Available

    The storage medium of all event subjects must be immediately available to the user

  • 2 - Any

    The event subjects may or may not be available

Zeitgeist Client API

ZeitgeistClient

class zeitgeist.client.ZeitgeistClient

Convenience APIs to have a Pythonic way to call 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.

find_event_ids_for_template(event_template, ids_reply_handler, **kwargs)

Send a query matching a single Event-template to the Zeitgeist event log. If the 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.

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.

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.

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)

Send a query for events matching the keyword arguments passed to this function. The allowed keywords are the same as the ones allowed by Event.new_for_values().

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.

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.

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.

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.

DBus API

This is the raw DBus API for the Zeitgeist engine. Applications written in Python are encouraged to use the ZeitgeistClient API instead.

org.gnome.zeitgeist.Log

class _zeitgeist.engine.remote.RemoteInterface(start_dbus=True, mainloop=None)
InsertEvents(events)

Inserts events into the log. Returns an array containing the ids of the inserted events

Parameter:events – List of events to be inserted in the log. If you are using the Python bindings you may pass Event instances directly to this method
Returns:An array containing the event ids of the inserted events. In case the any of the events where already logged the id of the existing event will be returned
Return type:Array of unsigned 32 bits integers. DBus signature au.
GetEvents(event_ids)

Get full event data for a set of event ids

Parameter:event_ids (Array of unsigned 32 bit integers. DBus signature au) – An array of event ids. Fx. obtained by calling FindEventIds()
Returns:Full event data for all the requested ids. The event data can be conveniently converted into a list of Event instances by calling events = map(Event, result)
Return type:A list of serialized events. DBus signature a(asaasay).
FindEventIds(time_range, event_templates, storage_state, num_events, result_type)

Search for events matching a given set of templates and return the ids of matching events. Use GetEvents() passing in the returned ids to look up the full event data.

The matching is done where unset fields in the templates are treated as wildcards. If a template has more than one subject then events will match the template if any one of their subjects match any one of the subject templates.

Parameters:
  • time_range (tuple of 64 bit integers. DBus signature (xx)) – two timestamps defining the timerange for the query. When using the Python bindings for Zeitgeist you may pass a TimeRange instance directly to this method
  • event_templates (array of events. DBus signature a(asaasay)) – An array of event templates which the returned events should match at least one of. When using the Python bindings for Zeitgeist you may pass a list of Event instances directly to this method.
  • storage_state (unsigned integer) – whether the item is currently known to be available. The list of possible values is enumerated in StorageState class
  • num_events (unsigned integer) – maximal amount of returned events
  • order (unsigned integer) – unsigned integer representing a result type
Returns:

An array containing the ids of all matching events, up to a maximum of num_events events. Sorted and grouped as defined by the result_type parameter.

Return type:

Array of unsigned 32 bit integers

DeleteEvents(ids)

Delete a set of events from the log given their ids

Parameter:ids (list of integers) – list of event ids obtained, for example, by calling FindEventIds()
DeleteLog()

Delete the log file and all its content

This method is used to delete the entire log file and all its content in one go. To delete specific subsets use FindEventIds() combined with DeleteEvents().

Quit()
Terminate the running Zeitgeist engine process; use with caution, this action must only be triggered with the user’s explicit consent, as it will affect all applications using Zeitgeist