Commits

Marcin Kasperski committed 8193c9f

Doc updates, small refactorings

Comments (0)

Files changed (5)

src/mekk/rtm/__access__.py

-
-API="Y2IwYzQ1ZGUwNDI5NTFiNDJjYjUzYzhmNjI0NjliMjk="
-SEC="Y2QyODU4Yzk0ZTQ2ZjdhNg=="
-

src/mekk/rtm/connect.py

 # -*- coding: utf-8 -*-
 
-from __access__ import API, SEC
 import webbrowser
 import keyring
-from base64 import decodestring as __
-from rtm_client import RtmClient
 from rtm_connector import RtmConnector, RtmException, RtmServiceException
 import getpass
 
             keyring.set_password(app_name, TOKEN_LABEL, connector.token)
             print "Access token saved"
         else:
-            raise Exception("Failed to grab access token")
+            raise RtmServiceException("Failed to grab access token")
 
     return connector
 
             keyring.set_password(app_name, SEC_LABEL, "")
         raise
 
-def create_rtm_client(app_name = "mekk-rtm", permission = "delete"):
-    """
-    Configures and creates connected and authorized RtmClient.
-    May use browser authorization to grab necessary permissions.
-    Uses embedded API key, so appropriate only for scripts embedded
-    in library!
-    """
-    connector = create_and_authorize_connector(
-        app_name, __(API), __(SEC), permission)
-    client = RtmClient(connector)
-    return client

src/mekk/rtm/helpers/__access__.py

+
+API="Y2IwYzQ1ZGUwNDI5NTFiNDJjYjUzYzhmNjI0NjliMjk="
+SEC="Y2QyODU4Yzk0ZTQ2ZjdhNg=="
+

src/mekk/rtm/helpers/connect.py

+from __access__ import API, SEC
+
+from mekk.rtm.connect import create_and_authorize_connector
+from mekk.rtm.client import RtmClient
+from base64 import decodestring as __
+
+def create_rtm_client(app_name = "mekk-rtm", permission = "delete"):
+    """
+    Configures and creates connected and authorized RtmClient.
+    May use browser authorization to grab necessary permissions.
+    Uses embedded API key, so appropriate only for scripts embedded
+    in library!
+    """
+    connector = create_and_authorize_connector(
+        app_name, __(API), __(SEC), permission)
+    client = RtmClient(connector)
+    return client

src/mekk/rtm/rtm_client.py

 from mekk.rtm.rtm_connector import RtmException
 import datetime
 
+############################################################
+# Helper structures (representations of RTM data)
+############################################################
+
+"""
+See RtmClient class for API documentation.
+
+The following structures (namedtuples) are used to represent
+data downloaded from RememberTheMilk
+
+List (normal list):
+- id (string) - unique id
+- name (string) - list name
+- archived (bool) - is the list archived (true) or active (false)
+"""
 List = namedtuple('List', 'id name archived')  
+
+"""
+Smart list (query):
+- id, name, archived - as in List
+- filter (string) - smartlist query (as defined via web interface)
+"""
 SmartList = namedtuple('SmartList', 'id name filter archived')
-# List representations. id, name and filter are strings, archived is bool
 
+"""
+Note (extra text appended to task)
+- id (string) - unique id (inside task)
+- title (string) - note title
+- body (string) - note text (can contain newlines)
+"""
 Note = namedtuple('Note', 'id title body')
-# All fields are strings
 
+"""
+Unique identification of individual task:
+- list_id (string) - identification of list the task belons to
+- taskseries_id (string) - ...
+- task_id (string) - id of task as such
+"""
 TaskKey = namedtuple('TaskKey', 'list_id task_id taskseries_id')
-# All fields are strings
 
+"""
+All task data:
+- key (TaskKey) - task identification
+- name (string) - task description
+- tags (list of strings, can be empty) - all task tags
+- notes (list of Note objects, can be empty) - all notes appended to task
+- due (datetime.datetime or None) - due date, can be None when not set
+- estimate (string or None) - estimated cost in RTM jargon (f.e. "5 hours"), None when unset
+- priority (int or None) - priority (1,2,3 or None when unset)
+- completed (bool) - is the task already completed?
+- postponed (int) - how many times task was postponed (0 if never)
+- repeat (string or None) - textual description of repeating clause
+     (currently sth like "every FREQ=DAILY;INTERVAL=3", in the future
+      can change to sth more sensible)
+- url (string or None) - url bound to task if any
+- deleted (bool) - set to true if the task has been deleted (can happen only
+      in result of delete method)
+"""
 Task = namedtuple('Task', 'key name tags notes due estimate priority completed postponed repeat url deleted')
-# key is TaskKey, tags and notes are lists (maybe empty), due is datetime or None,
-# priority is int or None, completed is datetime (if completed) or None, 
-# postponed is int, remaining fields are strings
 
-class RtmDataException(RtmException): pass
+class RtmDataException(RtmException): 
+    """
+    Exception thrown when the data structure is not understood by the library.
+    """
+    pass
 
 
-# Note: I abstract TaskSeries->Task hierarchy, using only Tasks
-# (and adding taskseries attributes to them). I am not quite
-# sure what are taskseries for but any update api require specific task.
+# Implementation note: I abstract TaskSeries->Task hierarchy, using
+# only Tasks (and adding taskseries as attribute to them). While taskseries
+# help aggregate some attributes in case of repeating tasks, I don't feel
+# they are of much use from the client point of view.
 
 class RtmClient(object):
     """
 
     Apart from wrapping RememberTheMilk API quirks it:
 
-    - keeps the cache of known lists to avoid re-downloading them
-    - handles duplicate detection in case of lists (so the same list
+    - keeps the cache of known lists to avoid re-downloading them and
+      handles duplicate detection in case of lists (so the same list
       is not created again)
-    - abstracts over some differences in data structure and format,
-      providing explicit API.
+
+    - abstracts over some differences in data structure and format
+      providing uniform API.
       
-
     All updates are performed inside single timeline (Rtm undo
     context) unless set_undo_point routine is called.
     """
         """
         Initializes object. 
 
-        @param connector authorized RtmConnector object used to handle communication.
+        @param connector authorized mekk.rtm.RtmConnector object used to
+               handle communication. Usually created using
+               functions from mekk.rtm.connect module
         """
         self.connector = connector
         self._list_cache = None      # name -> List