Commits

Marcin Kasperski committed e121e5d

doc updates

  • Participants
  • Parent commits 8193c9f

Comments (0)

Files changed (2)

File src/mekk/rtm/connect.py

 # -*- coding: utf-8 -*-
 
+"""
+Routines which make it easier to connect application in 
+console application/script case and some desktop cases. 
+"""
+
 import webbrowser
 import keyring
 from rtm_connector import RtmConnector, RtmException, RtmServiceException
     invite_to_authorize = _console_invite_to_auth,
     wait_for_authorization = _console_wait_for_user):
     """
-    Creates and returns RtmConnectr object. Ensures it contains
+    Creates and returns RtmConnector object. Ensures it contains
     valid access token (if not, performs browser-based authorization).
     Grabbed token (if any) is saved in keyring for future use (using app_name
-    to distnguish use-cases)
+    to distnguish usage cases)
     """
     TOKEN_LABEL = "default-user-token"
 

File src/mekk/rtm/rtm_client.py

 
         Uses list cache for better performance.
 
-        Returns list object
+        Returns List object representing given list
         """
         self._load_list_cache_if_necessary()
         list_info = self._list_cache.get(list_name)
     def unarchive_list(self, list_id):
         """
         Unarchives list of given id, returns the List or SmartList
-        object for it.
+        object representing list state after the operation.
         """
         r = self.connector.call(
             "rtm.lists.unarchive", 
     def archive_list(self, list_id):
         """
         Archives list of given id, returns the List or SmartList
-        object for it.
+        object representing list state after the operation.
         """
         r = self.connector.call(
             "rtm.lists.archive",
         """
         Returns all known lists (except smartlists, only true lists are returned).
 
-        Return value is a list of List objects/tuples
+        Return value is a list of List namedtuples
         """
         self._load_list_cache_if_necessary()
         return self._list_cache.values()
 
         @param task_name 
         @param list_id list identifier, can be None (then Inbox is used)
-        @param tags list of tags (note: names can't contain ',')
-        @param completed is task already completed
-        @param priority  1, 2, or 3
-        @param due_date due date (datetime.date or ISO 8601 text, if zone-unaware assumed to be UTC)
+        @param tags list of tags (note: tags can't contain ',')
+        @param completed should task be immediately marked as completed?
+        @param priority  1, 2, or 3 (or None)
+        @param due_date due date (datetime.date or ISO 8601 text, if given date is zone-unaware, it is assumed to be UTC)
         @param estimate estimated cost (text like "3 days 2 hours 40 minutes")
-        @param repeat task repeating clause (text like "Every Tuesday", "Every month on the 4th", "Every week until 1/1/2007",
-                "After a week" etc. See http://www.rememberthemilk.com/help/answers/basics/repeatformat.rtm )
-        @param url - url related to the task
-        @param notes - list of pairs (title, text)
+        @param repeat task repeating clause (text like "Every Tuesday", "Every month on the 4th", "Every week until 1/1/2007", "After a week" etc. See http://www.rememberthemilk.com/help/answers/basics/repeatformat.rtm )
+        @param url webpage related to the task (or None)
+        @param notes list of pairs (title, text) representing notes to be added to the task
 
         @returns Task object representing the task
         """
         return RtmClient._parse_note(r['note'])
 
     def delete_task(self, task_key):
+        """
+        Deletes given task.
+        @returns: Task data after operation (with deleted=True)
+        """
         timeline = self._get_timeline()
         r = self.connector.call(
             "rtm.tasks.delete",
 
         Filter syntax: http://www.rememberthemilk.com/help/answers/search/advanced.rtm
 
-        yields all found tasks (acts as a generator, wrap with list() to get list)
+        The routine works as generator and yields all found tasks. To
+        get the results as list, just wrap it with list(), for example::
+        
+            my_items = list(client.find_tasks(list_id = inbox.id))
         """
         r = self.connector.call(
             "rtm.tasks.getList",
             list_id = list_id,
             filter = filter,
             last_sync = last_sync)
-        #from pprint import pprint
-        #pprint(r['tasks'])
         tasks = r['tasks'].get('list', [])
         if type(tasks) is dict:
             tasks = [ tasks ]
                     yield RtmClient._parse_task(list_id, taskseries, task)
 
     def set_undo_point(self):
+        """
+        Force creation of new timeline. Timelines are not really used 
+        in the library yet, so it is more marker of possible future 
+        development than anything else.
+        """
         # Just forgetting previous timeline. New one will be created before first update
         self._timeline = None