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

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 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 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 ‘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

zeitgeist.datamodel.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. This class provides a list of hard coded URI constants for programming convenience. In addition; each interpretation instance in this class has a display_name property, which is an internationalized string meant for end user display.

The interpretation types listed here are all subclasses of str and may be used anywhere a string would be used.

Interpretation.APPLICATION

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#Application

An item that is a launchable application. The item’s URI must point to the relevant .desktop file. (Display name: 'Applications')

Interpretation.BOOKMARK

http://www.semanticdesktop.org/ontologies/nfo/#Bookmark

A user defined bookmark. The same bookmark may only refer exectly one item. (Display name: 'Bookmarks')

Interpretation.BROADCAST_MESSAGE

https://zeitgeist-project.com/schema/1.0/core#BroadcastMessage

Small broadcasted message, like Twitter/Identica micro blogging (TBD in tracker). (Display name: 'Broadcasts')

Interpretation.CLOSE_EVENT

https://zeitgeist-project.com/schema/1.0/core#CloseEvent

Event type triggered when an item is closed. (Display name: 'Closed')

Interpretation.COMMENT

http://www.semanticdesktop.org/ontologies/2007/01/19/nie/#comment

User provided comment. (Display name: 'Comments')

Interpretation.CREATE_EVENT

https://zeitgeist-project.com/schema/1.0/core#CreateEvent

Event type triggered when an item is created. (Display name: 'Created')

Interpretation.DOCUMENT

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo/#Document

A document, presentation, spreadsheet, or other content centric item. (Display name: 'Documents')

Interpretation.EMAIL

http://www.semanticdesktop.org/ontologies/2007/03/22/nmo/#Email

An email is an email is an email. (Display name: 'Email')

Interpretation.ERROR_EVENT

https://zeitgeist-project.com/schema/1.0/core#ErrorEvent

Event type triggered when the user has encountered an error. (Display name: 'Errors')

Interpretation.FEED_MESSAGE

http://www.tracker-project.org/temp/mfo#FeedMessage

Any syndicated item, RSS, Atom, or other. (Display name: 'Feeds')

Interpretation.FOCUS_EVENT

https://zeitgeist-project.com/schema/1.0/core#FocusEvent

Event type triggered when the user has switched focus to a new item. (Display name: 'Focused')

Interpretation.IMAGE

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo/#Image

A photography, painting, or other digital image. (Display name: 'Images')

Interpretation.IM_MESSAGE

http://www.semanticdesktop.org/ontologies/2007/03/22/nmo/#IMMessage

A message received from an instant messaging service. (Display name: 'Messages')

Interpretation.MODIFY_EVENT

https://zeitgeist-project.com/schema/1.0/core#ModifyEvent

Event type triggered when an item is modified. (Display name: 'Modified')

Interpretation.MUSIC

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo/#Audio

Digital music or other creative audio work. (Display name: 'Music')

Interpretation.OPEN_EVENT

https://zeitgeist-project.com/schema/1.0/core#OpenEvent

Event type triggered when an item is visited or opened. (Display name: 'Opened')

Interpretation.RECEIVE_EVENT

https://zeitgeist-project.com/schema/1.0/core#ReceiveEvent

Event type triggered when the user has received an item from a remote host. (Display name: 'Received')

Interpretation.SAVE_EVENT

https://zeitgeist-project.com/schema/1.0/core#SaveEvent

Event type triggered when an item is saved. (Display name: 'Saved')

Interpretation.SEND_EVENT

https://zeitgeist-project.com/schema/1.0/core#SendEvent

Event type triggered when the user sends/emails an item or message to a remote host. (Display name: 'Send')

Interpretation.SOURCECODE

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo/#ManifestationCode

Code in a compilable or interpreted programming language. (Display name: 'Manifestation Code')

Interpretation.TAG

http://www.semanticdesktop.org/ontologies/2007/08/15/nao#Tag

User provided tags. The same tag may refer multiple items. (Display name: 'Tags')

Interpretation.UNKNOWN

https://zeitgeist-project.com/schema/1.0/core#UnknownInterpretation

An entity with an unknown interpretation. (Display name: 'Unknown')

Interpretation.VIDEO

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo/#Video

Any form of digital video, streaming and non-streaming alike. (Display name: 'Videos')

Interpretation.VISIT_EVENT

https://zeitgeist-project.com/schema/1.0/core#VisitEvent

Event type triggered when an item is visited or opened. (Display name: 'Visited')

Interpretation.WARN_EVENT

https://zeitgeist-project.com/schema/1.0/core#WarnEvent

Event type triggered when the user is warned about something. (Display name: 'Warnings')

Manifestation

zeitgeist.datamodel.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 is uniquely identified by a URI. This class provides a list of hard coded URI constants for programming convenience. In addition; each interpretation instance in this class has a display_name property, which is an internationalized string meant for end user display.

The manifestation types listed here are all subclasses of str and may be used anywhere a string would be used.

Manifestation.FILE

http://www.semanticdesktop.org/ontologies/nfo/#FileDataObject

An item stored on the local filesystem. (Display name: 'Files')

Manifestation.HEURISTIC_ACTIVITY

https://zeitgeist-project.com/schema/1.0/core#HeuristicActivity

An application has calculated via heuristics that some relationship is very probable. (Display name: 'Activities')

Manifestation.SCHEDULED_ACTIVITY

https://zeitgeist-project.com/schema/1.0/core#ScheduledActivity

An event that has been triggered by some long running task activated by the user. Fx. playing a song from a playlist. (Display name: 'Activities')

Manifestation.SYSTEM_RESOURCE

http://freedesktop.org/standards/xesam/1.0/core#SystemRessource

An item available through the host operating system, such as an installed application or manual page (TBD in tracker). (Display name: 'System Resources')

Manifestation.UNKNOWN

https://zeitgeist-project.com/schema/1.0/core#UnknownManifestation

An entity with an unknown manifestation. (Display name: 'Unknown')

Manifestation.USER_ACTIVITY

https://zeitgeist-project.com/schema/1.0/core#UserActivity

An item that has been created solely on the basis of user actions and is not otherwise stored in some physical location. (Display name: 'Activities')

Manifestation.USER_NOTIFICATION

https://zeitgeist-project.com/schema/1.0/core#UserNotification

An item that has been send as a notification to the user. (Display name: 'Notifications')

Manifestation.WEB_HISTORY

http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#WebHistory

An item that has been extracted from the user’s browsing history. (Display name: 'Web History')

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 the furtest past 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.

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 ascendently by popularity. (Integer value: 5)

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)

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.