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). See also the section on the event serialization format.

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. For applications the format of this field is base filename of the corresponding .desktop file with an app:// URI scheme. For example /usr/share/applications/firefox.desktop is encoded as app://firefox.desktop

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

in_time_range(time_range)

Check if the event timestamp lies within a TimeRange

interpretation

Read/write property defining the interpretation type of the event

manifestation

Read/write property defining the manifestation type of the event

matches_event(event)

Interpret self as the template an match event against it. This method is the dual method of matches_template().

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. Interpretations and manifestations are also matched if they are children of the types specified in event_template. 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.

classmethod 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.

classmethod new_for_struct(struct)

Returns a new Event instance or None if struct is a NULL_EVENT

classmethod 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. Interpretations and manifestations are also matched if they are children of the types specified in subject_template.

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 found
• 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 volume or the string “net” for resources requiring a network interface, and the string “deleted” for subjects that are deleted.

origin

Read/write property with the URI of the location where the subject can be found. For files this is the parent directory, or for downloaded files it would be the URL of the page where you clicked the download link

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 ‘net’ for items requiring network interface 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

A collection of Symbol objects which represents the interpretations defined by the zeitgeist ontology. For more information see Interpretations.

Manifestation

A collection of Symbol objects which represents the manifestations defined by the zeitgeist ontology. For more information see Manifestations.

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).

classmethod always()

Return a TimeRange from 0 (January 1, 1970) to the most distant future

begin

The begining timestamp of this time range

end

The end timestamp of this time range

classmethod from_now()

Return a TimeRange from the instant of invocation to the end of time

classmethod from_seconds_ago(sec)

Return a TimeRange ranging from “sec” seconds before the instant of invocation to the same.

intersect(time_range)

Return a new TimeRange that is the intersection of the two time range intervals. If the intersection is empty this method returns None.

is_always()

Returns True if this time range goes from timestamp 0 (January 1, 1970) -or lower- to the most distant future.

classmethod until_now()

Return a TimeRange from 0 to the instant of invocation

ResultType

zeitgeist.datamodel.ResultType

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

ResultType.MostRecentEvents

All events with the most recent events first. (Integer value: 0)

ResultType.LeastRecentEvents

All events with the oldest ones first. (Integer value: 1)

ResultType.MostRecentSubjects

One event for each subject only, ordered with the most recent events first. (Integer value: 2)

ResultType.LeastRecentSubjects

One event for each subject only, ordered with oldest events first. (Integer value: 3)

ResultType.MostPopularSubjects

One event for each subject only, ordered by the popularity of the subject. (Integer value: 4)

ResultType.LeastPopularSubjects

One event for each subject only, ordered ascendingly by popularity. (Integer value: 5)

ResultType.MostPopularActor

The last event of each different actor,ordered by the popularity of the actor. (Integer value: 6)

ResultType.LeastPopularActor

The last event of each different actor,ordered ascendingly by the popularity of the actor. (Integer value: 7)

ResultType.MostRecentActor

The Actor that has been used to most recently. (Integer value: 8)

ResultType.LeastRecentActor

The Actor that has been used to least recently. (Integer value: 9)

ResultType.MostRecentOrigin

The last event of each different origin. (Integer value: 10)

ResultType.LeastRecentOrigin

The first event of each different origin. (Integer value: 11)

ResultType.MostPopularOrigin

The last event of each different origin,ordered by the popularity of the origins. (Integer value: 12)

ResultType.LeastPopularOrigin

The last event of each different origin,ordered ascendingly by the popularity of the origin. (Integer value: 13)

ResultType.OldestActor

The first event of each different actor. (Integer value: 14)

StorageState

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.

StorageState.NotAvailable

The storage medium of the events subjects must not be available to the user. (Integer value: 0)

StorageState.Available

The storage medium of all event subjects must be immediately available to the user. (Integer value: 1)

StorageState.Any

The event subjects may or may not be available. (Integer value: 2)

DataSource

zeitgeist.datamodel.DataSource

Optimized and convenient data structure representing a datasource.

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). See also the section on the event serialization format.

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.

This is part of the org.gnome.zeitgeist.DataSourceRegistry extension.

NULL_EVENT

zeitgeist.datamodel.NULL_EVENT

Minimal Event representation, a tuple containing three empty lists. This NULL_EVENT is used by the API to indicate a queried but not available (not found or blocked) Event.