123
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: − + + + + + + + + + + Line 7:
Line 16: + + Line 20:
Line 31: + + + − === How do I provide a query to the datastore.find() method so that I can find datastore objects with a particular property? === + + − + + + + + + + + + + + + + Line 39:
Line 66: + + Line 48:
Line 77: − + Line 63:
Line 92: + + − + − + − + − + − + + + + − + − + − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Line 114:
Line 184: + + Line 141:
Line 213: + + + + + + + + + + + +
Development Team/Almanac/sugar.datastore.datastore (view source)
Revision as of 21:32, 23 February 2010
, 21:32, 23 February 2010moved Walter is a wanker 12/Almanac/sugar.datastore.datastore to Development Team/Almanac/sugar.datastore.datastore over redirect: revert
{{Sugar Almanac TOC}}
{{Almanac}}
{{Almanac TOC}}
= High Level Functionality of the Datastore =
Abstractly, the datastore is a place where all sugar activities and activity data are saved. The datastore saves both physical file data and metadata, both of which can be accessed by using the datastore API provided in the sugar.datastore package.
The Activity class in sugar includes write_file() and read_file() methods that automatically interface with the datastore at different points during the life of an activity. However, you can access the datastore API more directly if you want more control over custom objects that are supposed to be created in the datastore.
[[Image:datastore-diagram.jpg|Overview of the Datastore]]
= Datastore Helper Functions =
= Datastore Helper Functions =
<pre>
<pre>
from sugar.datastore import datastore
...
#This method creates a datastore object that will be saved for later use by this activity.
#This method creates a datastore object that will be saved for later use by this activity.
def _create_ds_object(self):
def _create_ds_object(self):
</pre>
</pre>
=== How do I provide a query to the datastore.find() method so that I can find datastore objects with a particular property? ===
'''IMPORTANT''' Do not rely on datastore.find() method in all cases, its behaviour could be changed in future releases;<br>there is only on thing for sure: to treat jobjects that were created within activity use:<br>datastore.find({'activity_id': <activity-id-of(and only of)-current-activity>, ...})
The datastore package includes a find() helper function that allows you to find things in the datastore. Belows is a very simple example use of find where I simply search for journal entries that have a title of 'file1.txt'. I think print out the title and file path for each retreived entry.
The datastore package includes a find() helper function that allows you to find things in the datastore. Belows is a very simple example use of find where I simply search for journal entries that have a title of 'file1.txt'. I think print out the title and file path for each retreived entry.
<pre>
<pre>
from sugar.datastore import datastore
...
ds_objects, num_objects = datastore.find({'title':'file1.txt'})
ds_objects, num_objects = datastore.find({'title':'file1.txt'})
print '------------------------- QUERY RESULTS ---------------------------'
print '------------------------- QUERY RESULTS ---------------------------'
print "Number of Objects: " + str(num_objects)
print "Number of Objects: " + str(num_objects)
for i in xrange (0, num_objects, 1):
for i in xrange (num_objects):
print "File Path: " + ds_objects[i].get_file_path()
print "File Path: " + ds_objects[i].get_file_path()
print "Title: " + ds_objects[i].metadata['title']
print "Title: " + ds_objects[i].metadata['title']
</pre>
</pre>
Separate elements of the dictionary are combined with AND, and each attribute can have a list which is combined with OR. For instance, the query
<pre>
datastore.find({'title':['this','that'],
'activity':'org.laptop.sugar.ReadActivity',
'mime_type':'application/pdf',
'mtime':{'start':datetime.today().replace(hour=0, minute=0, second=0),
'end':datetime.today().replace(hour=23, minute=59, second=59)}})
</pre>
would get all pdf files for the Read activity titled 'this' or 'that' which were modified today.
=== How do I delete datastore entries with a particular property? ===
=== How do I delete datastore entries with a particular property? ===
<pre>
<pre>
from sugar.datastore import datastore
...
### Method: _delete_dsobjects, deletes datastore objects where prop=val
### Method: _delete_dsobjects, deletes datastore objects where prop=val
# in the metadata
# in the metadata
#loop through and delete each datastore object found.
#loop through and delete each datastore object found.
for i in xrange (0, num_objects, 1):
for i in xrange (num_objects):
print 'DELETING ' + ds_objects[i].metadata['title'] + '...'
print 'DELETING ' + ds_objects[i].metadata['title'] + '...'
ds_objects[i].destroy()
ds_objects[i].destroy()
<pre>
<pre>
from sugar.datastore import datastore
...
#the datastore.get_unique_values() method should return a list of values
#the datastore.get_unique_values() method should return a list of values
unique_val_array = datastore.get_unique_values('activity')
unique_val_array = datastore.get_unique_values('activity')
#loop through list of values and print them out.
#loop through list of values and print them out.
for i in xrange(0, len(unique_val_array), 1):
for x in unique_val_array:
print str(unique_val_array[i])
print x
</pre>
</pre>
=== How do I get command line access to the files in my DataStore? ===
=== How do I get command line access to the files in my DataStore? ===
Use the dslinks.py script to generate a set of symbolic links. Then you can use the following script to copy selected datastore objects to a usb stick or sd chip.
Use the [http://wiki.laptop.org/go/Datastore_symbolic_links dslinks.py] script to generate a set of symbolic links. Then you can use a script similar to the following to copy selected datastore objects to a usb stick or sd chip. This version selects all the datastore objects that have a file extension of '.odt' (which are generated by abiword). To experiment with unix shell commands substitute 'echo $fn' for the 'cp -p $fn /media/KINGSTON'
<pre>
<pre>
#use the unix for command to iterate over the activities or file extensions of interest
#use the unix for command to iterate over the activities or file extensions of interest
for fn in `find /home/olpc/datalinks |grep write`;
for fn in `find /home/olpc/datalinks |grep .odt`;
do
do
cp -p fn /media/KINGSTON
cp -p $fn /media/KINGSTON
done
done
</pre>
</pre>
=== How do I identify the different mount points available through the datastore api? ===
=== How do I identify the different mount points available through the datastore api? ===
[http://wiki.laptop.org/go/Low-level_Activity_API#Mount_Points Mount points] help to abstract different locations where datastore objects can be stored. The following code uses the datastore.mounts() method to help print out all the mount points available, with each point identified by three key properties: title, uri and id.
[http://wiki.laptop.org/go/Low-level_Activity_API#Mount_Points Mount points] help to abstract different locations where datastore objects can be stored. The following code uses the datastore.mounts() method to help print out all the mount points available, with each point identified by three key properties: title, uri and id.
<pre>
<pre>
from sugar.datastore import datastore
...
#### Method: _print_all_mounts, prints all the mounts available.
#### Method: _print_all_mounts, prints all the mounts available.
def _print_all_mounts(self):
def _print_all_mounts(self):
print '------------------------MOUNTS--------------------------------'
print '------------------------MOUNTS--------------------------------'
ds_mounts = datastore.mounts()
ds_mounts = datastore.mounts()
for i in xrange(0, len(ds_mounts), 1):
for x in ds_mounts:
print '---------MOUNT---------'
print '---------MOUNT---------'
print 'title: '+ ds_mounts[i]['title']
print 'title: '+ x['title']
print 'uri: '+ ds_mounts[i]['uri']
print 'uri: '+ x['uri']
print 'id: ' + ds_mounts[i]['id']
print 'id: ' + x['id']
</pre>
</pre>
=== How do I save multiple files that are associated with a single activity? ===
You may be creating an activity that works with multiple files at once. For example, you may have a media editing activity that works with several sound and video files at once (perhaps combining them in to one output). In such cases, you need to be able to access multiple files from a single datastore entry.
= Class: DSObject =
= Class: DSObject =
=== How do I access the metadata entries for a datastore object? ===
Every DSObject created by datastore.create() has a metadata property. This property refers to a [[Low-level_Activity_API#Meta_Data|DS Object]], which contains the metadata for your datastore object. The code below shows how to read metadata values by referring to the metadata property of a DSObject. metadata is a Python dictionary object.
<pre>
from sugar.datastore import datastore
...
#my_dsobject is of type datastore.DSObject
#object_id is a datastore object (e.g., returned from the datastore Chooser)
my_dsobject = datastore.get(object_id)
#Access the 'description' property
print my_dsobject.metadata['description']
</pre>
This code snippet shows how to create a pixbuf from the preview entry in the datastore:
<pre>
from sugar.datastore import datastore
...
#my_dsobject is of type datastore.DSObject
#object_id is a datastore object
my_dsobject = datastore.get(object_id)
pixbufloader = gtk.gdk.pixbuf_loader_new_with_mime_type('image/png')
#Access the 'preview' property
#Note that the preview image is 300x225
pixbufloader.write(dsobject.metadata['preview'])
pixbufloader.close()
pixbuf = pixbufloader.get_pixbuf()
</pre>
=== How do I create new metadata entries or reassign metadata for a datastore object that has been created? ===
=== How do I create new metadata entries or reassign metadata for a datastore object that has been created? ===
Every DSObject created by datastore.create() has a metadata property. This property refers to a [[#Class: DSMetadata | DSMetadata object]], which contains the metadata for your datastore object. The code below shows how to assign metadata values by referring to the metadata property of a DSObject.
Every DSObject created by datastore.create() has a metadata property. This property refers to a [[#Class: DSMetadata | DSMetadata object]], which contains the metadata for your datastore object. The code below shows how to assign metadata values by referring to the metadata property of a DSObject.
<pre>
<pre>
from sugar.datastore import datastore
...
#my_dsobject is of type datastore.DSObject
#my_dsobject is of type datastore.DSObject
my_dsobject = datastore.create()
my_dsobject = datastore.create()
<pre>
<pre>
from sugar.datastore import datastore
...
#### Method: _write_textfile, which creates a simple text file
#### Method: _write_textfile, which creates a simple text file
# with filetext as the data put in the file.
# with filetext as the data put in the file.
return file_dsobject
return file_dsobject
</pre>
=== How do I resume an activity from the datastore programmatically? ===
Every DSObject instance has a resume() method that can be called to resume the activity associated with the object. The method below demonstrates:
<pre>
#### Method: _resume_activty, resumes an activity associated with
# the datastore object passed to this method.
def _resume_activity(self, ds_object):
print "********* Resuming " + ds_object.metadata['title']
ds_object.resume()
</pre>
</pre>