Re: Updates This Week to the Sugar Almanac - Using the Datastore and More
On Fri, Jun 27, 2008 at 5:17 PM, Faisal Anwar [EMAIL PROTECTED] wrote: Hi Tomeu, Thanks so much for the clarifications. I understand now the abstraction intended for metadata accessed through DSMetadata and DSObject and will try to write that up a little more forcefully. I guess the main thing I was concerned about was having a consistent and lasting interface to the datastore (which can certainly be implemented in the form of a dictionary if that is most appropriate). I hope this abstraction will hold moving forward so that activity developers are confident that their hooks in to datastore will work with the same behavior over time (this is part of the purpose of the documentation I'm working on). Yes, I'm confident that we'll be able to maintain compatibility with activities that use the current API, although I also hope that we'll come up with something much better soon. With regards to the lower level DBus calls in datastore and elsewhere, what I'm really looking out for is what levels of the tech stack an activity developer will need to learn to build a fairly robust and complex activity. Of course, for some things lower level Dbus calls may be unavoidable, but I'm assuming that there should be a substantive interface in python that abstracts away the Dbus functionality for most developers. As I go through more of the code in datastore, presence, and elsewhere, I'll try to identify cases where perhaps a low-level Dbus call could be abstracted to some standard python calls. Well, the low level API isn't really that hard to use. The dbus-python bindings already do a great work of making easier to use DBus services from python. If you find any capability in the low level bindings that could be useful to activities and is not yet in the python wrapper, please tell. Thanks, Tomeu ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates This Week to the Sugar Almanac - Using the Datastore and More
Hi Tomeu, Thanks so much for the clarifications. I understand now the abstraction intended for metadata accessed through DSMetadata and DSObject and will try to write that up a little more forcefully. I guess the main thing I was concerned about was having a consistent and lasting interface to the datastore (which can certainly be implemented in the form of a dictionary if that is most appropriate). I hope this abstraction will hold moving forward so that activity developers are confident that their hooks in to datastore will work with the same behavior over time (this is part of the purpose of the documentation I'm working on). With regards to the lower level DBus calls in datastore and elsewhere, what I'm really looking out for is what levels of the tech stack an activity developer will need to learn to build a fairly robust and complex activity. Of course, for some things lower level Dbus calls may be unavoidable, but I'm assuming that there should be a substantive interface in python that abstracts away the Dbus functionality for most developers. As I go through more of the code in datastore, presence, and elsewhere, I'll try to identify cases where perhaps a low-level Dbus call could be abstracted to some standard python calls. Faisal On Wed, Jun 25, 2008 at 4:28 AM, Tomeu Vizoso [EMAIL PROTECTED] wrote: Hi Faisal, some answers below: 2008/6/24 Faisal Anwar [EMAIL PROTECTED]: ?? 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 That class is to be used in the same way as dictionaries in python, so the API mimics that. By implementing __getitem__, __setitem__ and get(), the user can do the following: obj.metadata['my-property'] = 'blah blah' print obj.metadata['my-property'] print obj.metadata.get('my-property', 'N/A') ?? Several things that are currently documented at http://wiki.laptop.org/go/Low-level_Activity_API#Keeping_and_Resumingare 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. That page documents the low level API that can be used by all activities, no matter in which language are written. sugar.datastore is a higher level API only available to python activities. See here for the D-Bus API of the datastore: http://dev.laptop.org/git?p=projects/datastore;a=blob;f=src/olpc/datastore/datastore.py ?? 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? Well, datastore.delete() instructs the datastore to delete the object from its persistent storage. DSObject.destroy() is intended to be called when the user stops needing the transient instance that represents the persistent object. This is similar to DB programming with SQL in procedural languages, deleting the resultset object is not the same as deleting the rows that are contained in that resultset. 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. Nice work, more questions welcome. Regards, Tomeu ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates This Week to the Sugar Almanac - Using the Datastore and More
Hi Faisal, some answers below: 2008/6/24 Faisal Anwar [EMAIL PROTECTED]: ?? 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 That class is to be used in the same way as dictionaries in python, so the API mimics that. By implementing __getitem__, __setitem__ and get(), the user can do the following: obj.metadata['my-property'] = 'blah blah' print obj.metadata['my-property'] print obj.metadata.get('my-property', 'N/A') ?? 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. That page documents the low level API that can be used by all activities, no matter in which language are written. sugar.datastore is a higher level API only available to python activities. See here for the D-Bus API of the datastore: http://dev.laptop.org/git?p=projects/datastore;a=blob;f=src/olpc/datastore/datastore.py ?? 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? Well, datastore.delete() instructs the datastore to delete the object from its persistent storage. DSObject.destroy() is intended to be called when the user stops needing the transient instance that represents the persistent object. This is similar to DB programming with SQL in procedural languages, deleting the resultset object is not the same as deleting the rows that are contained in that resultset. 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. Nice work, more questions welcome. Regards, Tomeu ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Updates This Week to the Sugar Almanac - Using the Datastore and More
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 Functionshttp://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: DSObjecthttp://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 ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel