Merge lp:~thisfred/u1db/u1todo-whats-up-doc into lp:u1db

[Eric Casteleijn]

added a lot of running commentary

[lp:~thisfred/u1db/u1todo-whats-up-doc]

267. By Eric Casteleijn on 2012-05-09

merged trunk, resolved conflicts

[Lucio Torre (lucio.torre)]

review: Approve

=== modified file 'u1todo/u1todo.py'
--- u1todo/u1todo.py	2012-05-08 18:27:32 +0000
+++ u1todo/u1todo.py	2012-05-09 15:00:25 +0000
@@ -43,6 +43,8 @@
 
 def extract_tags(text):
     """Extract the tags from the text."""
+    # This looks for all "tags" in a text, indicated with a '#' at the
+    # start of the tag, or enclosed in square brackets.
     return [t[0] if t[0] else t[1] for t in TAGS.findall(text)]
 
 
@@ -54,7 +56,9 @@
 
     def initialize_db(self):
         """Initialize the database."""
+        # Ask the database for currently existing indexes.
         db_indexes = dict(self.db.list_indexes())
+        # Loop through the indexes we expect to find.
         for name, expression in INDEXES.items():
             if name not in db_indexes:
                 # The index does not yet exist.
@@ -63,7 +67,8 @@
             if expression == db_indexes[name]:
                 # The index exists and is up to date.
                 continue
-            # The index exists but the definition is out of date.
+            # The index exists but the definition is not what expected, so we
+            # delete it and add the proper index expression.
             self.db.delete_index(name)
             self.db.create_index(name, expression)
 
@@ -72,33 +77,48 @@
         task.tags = tags
 
     def get_all_tags(self):
-        """Get all the tags in use."""
+        """Get all tags in use in the entire database."""
         return self.db.get_index_keys(TAGS_INDEX)
 
     def get_tasks_by_tags(self, tags):
+        """Get all tasks that have every tag in tags."""
         if not tags:
+            # No tags specified, so return all tasks.
             return self.get_all_tasks()
+        # Get all tasks for the first tag.
         results = {
             doc.doc_id: doc for doc in
             self.db.get_from_index(TAGS_INDEX, [(tags[0],)])}
+        # Now loop over the rest of the tags (if any) and remove from the
+        # results any document that does not have that particular tag.
         for tag in tags[1:]:
+            # Get the ids of all documents with this tag.
             ids = [
                 doc.doc_id for doc in
                 self.db.get_from_index(TAGS_INDEX, [(tag,)])]
             for key in results.keys():
                 if key not in ids:
+                    # Remove the document from result, because it does not have
+                    # this particular tag.
                     del results[key]
                     if not results:
+                        # If results is empty, we're done: there are no
+                        # documents with all tags.
                         return []
+        # Wrap each document in results in a Task object, and return them.
         return [Task(doc) for doc in results.values()]
 
     def get_task(self, task_id):
         """Get a task from the database."""
         document = self.db.get_doc(task_id)
         if document is None:
+            # No document with that id exists in the database.
             raise KeyError("No task with id '%s'." % (task_id,))
         if document.content is None:
+            # The document id exists, but the document's content was previously
+            # deleted.
             raise KeyError("Task with id %s was deleted." % (task_id,))
+        # Wrap the document in a Task object and return it.
         return Task(document)
 
     def delete_task(self, task):
@@ -107,15 +127,23 @@
 
     def new_task(self, title=None, tags=None):
         """Create a new task document."""
-        # Create the document in the u1db database
         if tags is None:
             tags = []
+        # We copy the JSON string representing a pristine task with no title
+        # and no tags.
         content = EMPTY_TASK
+        # If we were passed a title or tags, or both, we set them in the object
+        # before storing it in the database.
         if title or tags:
+            # Load the json string into a Python object.
             content_object = json.loads(content)
             content_object['title'] = title
             content_object['tags'] = tags
+            # Convert the Python object back into a JSON string.
             content = json.dumps(content_object)
+        # Store the document in the database. Since we did not set a document
+        # id, the database will store it as a new document, and generate
+        # a valid id.
         document = self.db.create_doc(content=content)
         # Wrap the document in a Task object.
         return Task(document)
@@ -127,6 +155,9 @@
         self.db.put_doc(task.document)
 
     def get_all_tasks(self):
+        # Since the DONE_INDEX indexes anything that has a value in the field
+        # "done", and all tasks do (either True or False), it's a good way to
+        # get all tasks out of the database.
         return [
             Task(doc) for doc in self.db.get_from_index(DONE_INDEX, ["*"])]
 
@@ -141,6 +172,8 @@
     @property
     def task_id(self):
         """The u1db id of the task."""
+        # Since we won't ever change this, but it's handy for comparing
+        # different Task objects, it's a read only property.
         return self._document.doc_id
 
     def _get_title(self):
@@ -148,7 +181,7 @@
         return self._content['title']
 
     def _set_title(self, title):
-        """Set the task title and save to db."""
+        """Set the task title."""
         self._content['title'] = title
 
     title = property(_get_title, _set_title, doc="Title of the task.")
@@ -176,5 +209,7 @@
     @property
     def document(self):
         """The u1db document representing this task."""
+        # This brings the underlying document's JSON content back into sync
+        # with whatever data the task currently holds.
         self._document.content = json.dumps(self._content)
         return self._document

=== modified file 'u1todo/ui.py'
--- u1todo/ui.py	2012-05-08 20:44:41 +0000
+++ u1todo/ui.py	2012-05-09 15:00:25 +0000
@@ -37,7 +37,9 @@
     def __init__(self, task):
         super(UITask, self).__init__()
         self.task = task
+        # Set the list item's text to the task's title.
         self.setText(self.task.title)
+        # If the task is done, check off the list item.
         self.setCheckState(
             QtCore.Qt.Checked if task.done else QtCore.Qt.Unchecked)
         self.update_strikethrough()
@@ -53,49 +55,80 @@
 
     def __init__(self, in_memory=False):
         super(Main, self).__init__()
-        uifile = os.path.join(os.path.abspath(os.path.dirname(__file__)),
-                              'u1todo.ui')
+        # Dynamically load the ui file generated by QtDesigner.
+        uifile = os.path.join(
+            os.path.abspath(os.path.dirname(__file__)), 'u1todo.ui')
         uic.loadUi(uifile, self)
+        # hook up the signals to the signal handlers.
         self.connect_events()
+        # Load the u1todo database.
         db = get_database()
+        # And wrap it in a TodoStore object.
         self.store = TodoStore(db)
         # create or update the indexes if they are not up-to-date
         self.store.initialize_db()
+        # Initially the delete button is disabled, because there are no tasks
+        # to delete.
         self.delete_button.setEnabled(False)
+        # Initialize some variables we will use to keep track of the tags.
         self._tag_docs = defaultdict(list)
         self._tag_buttons = {}
         self._tag_filter = []
+        # Get all the tasks in the database, and add them to the UI.
         for task in self.store.get_all_tasks():
             self.add_task(task)
         self.task_edit.clear()
+        # Give the edit field focus.
         self.task_edit.setFocus()
+        # Initialize the variable that points to the currently selected list
+        # item.
         self.item = None
 
     def connect_events(self):
         """Hook up all the signal handlers."""
+        # On enter, save the task that was being edited.
         self.task_edit.returnPressed.connect(self.update)
+        # When the Edit/Add button is clicked, save the task that was being
+        # edited.
         self.edit_button.clicked.connect(self.update)
+        # When the Delete button is clicked, delete the currently selected task
+        # (if any.)
         self.delete_button.clicked.connect(self.delete)
+        # If a new row in the list is selected, change the currently selected
+        # task, and put its contents in the edit field.
         self.todo_list.currentRowChanged.connect(self.row_changed)
+        # If the checked status of an item in the list changes, change the done
+        # status of the task.
         self.todo_list.itemChanged.connect(self.item_changed)
         self.sync_button.clicked.connect(self.synchronize)
 
     def refresh_filter(self):
+        """Remove all tasks, and show only those that satisfy the new filter.
+
+        """
+        # Remove everything from the list.
         while len(self.todo_list):
             self.todo_list.takeItem(0)
+        # Get the filtered tasks from the database.
         for task in self.store.get_tasks_by_tags(self._tag_filter):
+            # Add them to the UI.
             self.add_task(task)
+        # Clear the current selection.
+        self.todo_list.setCurrentRow(-1)
+        self.task_edit.clear()
         self.item = None
-        self.task_edit.clear()
 
     def item_changed(self, item):
+        """Mark a task as done or not done."""
         if item.checkState() == QtCore.Qt.Checked:
             item.task.done = True
         else:
             item.task.done = False
+        # Save the task to the database.
         item.update_strikethrough()
         item.setText(item.task.title)
         self.store.save_task(item.task)
+        # Clear the current selection.
         self.todo_list.setCurrentRow(-1)
         self.task_edit.clear()
         self.item = None
@@ -104,12 +137,16 @@
         """Either add a new task or update an existing one."""
         text = unicode(self.task_edit.text(), 'utf-8')
         if not text:
+            # There was no text in the edit field so do nothing.
             return
         if self.item is None:
+            # No task was selected, so add a new one.
             task = self.store.new_task(text, tags=extract_tags(text))
             self.add_task(task)
         else:
+            # A task was selected, so update it.
             self.update_task_text(text)
+        # Clear the current selection.
         self.todo_list.setCurrentRow(-1)
         self.task_edit.clear()
         self.item = None
@@ -161,56 +198,102 @@
 
     def delete(self):
         """Delete a todo item."""
+        # Delete the item from the database.
         row = self.todo_list.currentRow()
         item = self.todo_list.takeItem(row)
         if item is None:
             return
         self.store.delete_task(item.task)
+        # Clear the current selection.
         self.todo_list.setCurrentRow(-1)
+        self.task_edit.clear()
+        self.item = None
         if self.todo_list.count() == 0:
+            # If there are no tasks left, disable the delete button.
             self.delete_button.setEnabled(False)
 
     def add_task(self, task):
         """Add a new todo item."""
+        # Wrap the task in a UITask object.
         item = UITask(task)
         self.todo_list.addItem(item)
+        # We know there is at least one item now so we enable the delete
+        # button.
         self.delete_button.setEnabled(True)
         if not task.tags:
             return
+        # If the task has tags, we add them as filter buttons to the UI, if
+        # they are new.
         for tag in task.tags:
             self.add_tag(task.task_id, tag)
 
     def add_tag(self, task_id, tag):
+        """Create a link between the task with id task_id and the tag, and
+        add a new button for tag if it was not already there.
+
+        """
+        # Add the task id to the list of document ids associated with this tag.
         self._tag_docs[tag].append(task_id)
+        # If the list has more than one element the tag button was already
+        # present.
         if len(self._tag_docs[tag]) > 1:
             return
+        # Add a tag filter button for this tag to the UI.
         button = QtGui.QPushButton(tag)
         button._u1todo_tag = tag
+        # Make the button an on/off button.
         button.setCheckable(True)
+        # Store a reference to the button in a dictionary so we can find it
+        # back more easily if we need to delete it.
         self._tag_buttons[tag] = button
 
+        # We define a function to handle the clicked signal of the button,
+        # since each button will need its own handler.
         def filter_toggle(checked):
+            """Toggle the filter for the tag associated with this button."""
             if checked:
+                # Add the tag to the current filter.
                 self._tag_filter.append(button._u1todo_tag)
             else:
+                # Remove the tag from the current filter.
                 self._tag_filter.remove(button._u1todo_tag)
+            # Apply the new filter.
             self.refresh_filter()
 
+        # Attach the handler to the button's clicked signal.
         button.clicked.connect(filter_toggle)
+        # Get the position where the button needs to be inserted. (We keep them
+        # sorted alphabetically by the text of the tag.
         index = sorted(self._tag_buttons.keys()).index(tag)
+        # And add the button to the UI.
         self.tag_buttons.insertWidget(index, button)
 
     def remove_tag(self, task_id, tag):
+        """Remove the link between the task with id task_id and the tag, and
+        remove the button for tag if it no longer has any tasks associated with
+        it.
+
+        """
+        # Remove the task id from the list of document ids associated with this
+        # tag.
         self._tag_docs[tag].remove(task_id)
+        # If the list is not empty, we do not remove the button, because there
+        # are still tasks that have this tag.
         if self._tag_docs[tag]:
             return
+        # Look up the button.
         button = self._tag_buttons[tag]
+        # Remove it from the ui.
         self.tag_buttons.removeWidget(button)
+        # And remove the reference.
         del self._tag_buttons[tag]
 
     def update_tags(self, task_id, old_tags, new_tags):
+        """Process any changed tags for this task_id."""
+        # Process all removed tags.
         for tag in old_tags - new_tags:
             self.remove_tag(task_id, tag)
+        # Process all tags newly added.
         for tag in new_tags - old_tags:
             self.add_tag(task_id, tag)
 
@@ -218,16 +301,23 @@
         """Edit an existing todo item."""
         item = self.item
         task = item.task
+        # Change the task's title to the text in the edit field.
         task.title = text
+        # Record the current tags.
         old_tags = set(task.tags) if task.tags else set([])
+        # Extract the new tags from the new text.
         new_tags = set(extract_tags(text))
+        # Check if the tag filter buttons need updating.
         self.update_tags(item.task.task_id, old_tags, new_tags)
+        # Set the tags on the task.
         task.tags = list(new_tags)
         # disconnect the signal temporarily while we change the title
         self.todo_list.itemChanged.disconnect(self.item_changed)
+        # Change the text in the UI.
         item.setText(text)
         # reconnect the signal after we changed the title
         self.todo_list.itemChanged.connect(self.item_changed)
+        # Save the changed task to the database.
         self.store.save_task(task)
 
     def row_changed(self, index):
@@ -235,12 +325,10 @@
         if index == -1:
             self.task_edit.clear()
             return
-        self.edit_item(self.todo_list.item(index))
-
-    def edit_item(self, item):
-        """Edit item in task edit box."""
-        self.item = item
-        self.task_edit.setText(item.task.title)
+        # If a row is selected, show the selected task's title in the edit
+        # field.
+        self.item = self.todo_list.item(index)
+        self.task_edit.setText(self.item.task.title)
 
 
 if __name__ == "__main__":