[sugar] Updates This Week to the Sugar Almanac - Using the Datastore and More

[Faisal Anwar]

Hello All,

First off, thanks to everyone who has been contributing to the almanac (
http://wiki.laptop.org/go/Sugar-api-doc) directly or giving me feedback on
things that need to be added or improved for accuracy. Please keep the
feedback coming.

Among many other additions, the Sugar Almanac now has a section on using the
datastore. It includes a basic overview of the architecture as well as a
bunch of entries on how to do different useful tasks with the datastore:


   - 2 Datastore Helper
Functions<http://wiki.laptop.org/go/Sugar.datastore.datastore#Datastore_Helper_Functions>
      - 2.1 How do I create a new datastore
object?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_create_a_new_datastore_object.3F>
      - 2.2 How do I provide a query to the datastore.find() method so that
      I can find datastore objects with a particular
property?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_provide_a_query_to_the_datastore.find.28.29_method_so_that_I_can_find_datastore_objects_with_a_particular_property.3F>
      - 2.3 How do I delete datastore entries with a particular
property?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_delete_datastore_entries_with_a_particular_property.3F>
      - 2.4 How do I get all the unique values that are mapped to a
      particular key in the
datastore?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_get_all_the_unique_values_that_are_mapped_to_a_particular_key_in_the_datastore.3F>
      - 2.5 How do I get command line access to the files in my
DataStore?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_get_command_line_access_to_the_files_in_my_DataStore.3F>
      - 2.6 How do I identify the different mount points available through
      the datastore
api?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_identify_the_different_mount_points_available_through_the_datastore_api.3F>
   - 3 Class: DSObject<http://wiki.laptop.org/go/Sugar.datastore.datastore#Class:_DSObject>
      - 3.1 How do I create new metadata entries or reassign metadata for a
      datastore object that has been
created?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_create_new_metadata_entries_or_reassign_metadata_for_a_datastore_object_that_has_been_created.3F>
      - 3.2 How do I save a simple text file to the
datastore?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_save_a_simple_text_file_to_the_datastore.3F>
      - 3.3 How do I resume an activity from the datastore
programmatically?<http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_resume_an_activity_from_the_datastore_programmatically.3F>


Also, for those who are experienced with writing the actual datastore code,
I had the following questions that came up while trying to understand how
this module works:

?? Is there a specific reason why there isn't a "set()" method in the
datastore.DSMetadata class? Shouldn't people be given standard accessors and
mutators to work with this code. This is especially confusing because it
seems there is presently a "get()" method, but the set() method does not
exist (so the abstraction is completely different based on whether you are
getting or setting data). d

?? Several things that are currently documented at
http://wiki.laptop.org/go/Low-level_Activity_API#Keeping_and_Resuming are
outdated. Specifically, it says datastore.create() returns the object_id.
That's wrong, it returns the actual DSObject. Furthermore, it says there are
methods called datastore.update and datastore.get_properties, but they don't
exists.

?? The deletion/destruction of datastore activities seems to be a little
confusing. In particular, there is a datastore.delete() method and there is
also a DSObject.destroy() method. Why doesn't datastore.delete() simply call
the destroy() method in its code so that any files associated with the
deleted datastore object are also removed. Given that a warning is thrown
telling the developer that an object is deleted without directly calling
DSObject.destroy() (it is called indirectly through the __del__ method, but
why not have things more explicit?), I'm not sure why this isn't just done
programmatically. Is there ever a reason why one woul perform a delete() on
an object without doing the functionality in DSObject.destroy() and are any
of these reasons compelling enough that we should keep the delete() and
destroy() methods as they are now?


Other questions may come up as people work more on this documentation. In
the meantime, I'd greatly appreciate any feedback on the existing work and
also any answers to the questions above.



Faisal
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.laptop.org/pipermail/sugar/attachments/20080624/b0e75b67/attachment.htm