GTG

Merge lp:~jml/gtg/docstrings-for-requester into lp:~gtg/gtg/old-trunk

  1. docstrings-for-requester
  2. Merge into old-trunk
Proposed by Jonathan Lange
Status: Merged
Merged at revision: not available
Proposed branch: lp:~jml/gtg/docstrings-for-requester
Merge into: lp:~gtg/gtg/old-trunk
Diff against target: None lines
To merge this branch: bzr merge lp:~jml/gtg/docstrings-for-requester
Reviewer Review Type Date Requested Status
Gtg developers Pending
Review via email: mp+8666@code.launchpad.net
To post a comment you must log in.
Revision history for this message
Jonathan Lange (jml) wrote :

This changes all of the comments in the requester module into docstrings. It also removes any trailing whitespace, removes any unnecessary backslashes, deletes spaces before colons (PEP 8 violation), adds spaces after commas (PEP 8 violation), puts spaces after the '#' symbol on comments, fixes spelling on comments and tries to expand the docstrings where appropriate.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'GTG/core/requester.py'
2--- GTG/core/requester.py 2009-03-29 19:32:59 +0000
3+++ GTG/core/requester.py 2009-07-13 03:50:25 +0000
4@@ -19,182 +19,238 @@
5
6
7 from GTG.tools.listes import *
8-#Requester is a pure View object. It will not do anything but it will
9-#be used by any Interface to handle the requests to the datastore
10-
11-#There could be multiple requester. It means that a requester should never
12-#Hold any data except a reference to its datastore.
13+
14+
15 class Requester :
16- def __init__(self,datastore) :
17+ """A view on a GTG datastore.
18+
19+ `Requester` is a stateless object that simply provides a nice API for user
20+ interfaces to use for datastore operations.
21+
22+ Multiple `Requester`s can exist on the same datastore, so they should
23+ never have state of their own.
24+ """
25+
26+ def __init__(self, datastore):
27+ """Construct a `Requester`."""
28 self.ds = datastore
29-
30- def connect(self,signal,func) :
31- self.ds.connect(signal,func)
32-
33+
34+ def connect(self, signal, func):
35+ self.ds.connect(signal, func)
36+
37 ############## Tasks ##########################
38 ###############################################
39
40-
41- #Return True if the task exists
42- def has_task(self,tid) :
43+ def has_task(self, tid):
44+ """Does the task 'tid' exist?"""
45 return self.ds.has_task(tid)
46-
47- #Get the task with the given pid
48- #If the task doesn't exist, we create it and force the pid
49- def get_task(self,tid) :
50+
51+ def get_task(self, tid):
52+ """Get the task with the given 'tid'.
53+
54+ If no such task exists, create it and force the tid to be 'tid'.
55+
56+ :param tid: The task id.
57+ :return: A task.
58+ """
59 task = self.ds.get_task(tid)
60 return task
61-
62- #Pid is the project in which the new task will be created
63- #MODIFICATION class (the data will be modified)
64- def new_task(self,pid=None,tags=None,newtask=True) :
65- task = self.ds.new_task(pid=pid,newtask=newtask)
66- if tags :
67- for t in tags :
68+
69+ def new_task(self, pid=None, tags=None, newtask=True):
70+ """Create a new task.
71+
72+ Note: this modifies the datastore.
73+
74+ :param pid: The project where the new task will be created.
75+ :param tags: The tags for the new task. If not provided, then the
76+ task will have no tags.
77+ :param newtask: 'True' if this is creating a task, 'False' if
78+ importing an existing task.
79+ """
80+ # XXX: The docs don't make it clear why you'd ever need to pass in
81+ # newtask or how newtask is used.
82+ task = self.ds.new_task(pid=pid, newtask=newtask)
83+ if tags:
84+ for t in tags:
85 task.add_tag(t.get_name())
86 return task
87-
88-
89- #MODIFICATION class (the data will be modified)
90- def delete_task(self,tid) :
91+
92+ def delete_task(self, tid):
93+ """Delete the task 'tid'.
94+
95+ Note: this modifies the datastore.
96+
97+ :param tid: The id of the task to be deleted.
98+ """
99 self.ds.delete_task(tid)
100-
101- #Return a list of active tasks tid
102- #
103- # tags = []. All tasks will have at least one of those tags.
104- # If None, all tasks are eligible
105- #
106- # Status = [] : a list of status to choose from
107- # available status are : Active - Done - Dismiss - Deleted
108- # If none, all tasks are eligible
109- #
110- # notag_only : if True, only tasks without tags are selected
111- #
112- # started_only : if True, only tasks with an already passed started date are selected
113- # (task with no startdate are considered as started)
114- #
115- # is_root : if True, only tasks that have no parent in the current selection
116- # are eligible. If False, all tasks are eligible
117- def get_tasks_list(self,tags=None, status=["Active"],notag_only=False,\
118- started_only=True,is_root=False) :
119+
120+ def get_tasks_list(self, tags=None, status=["Active"], notag_only=False,
121+ started_only=True, is_root=False):
122+ """Return a list of tids of tasks.
123+
124+ By default, returns a list of all the tids of all active tasks.
125+
126+ :param tags: A list of tags. If provided, restricts the list of
127+ returned tasks to those that have one or more of these tags.
128+ :param status: A list of statuses. If provided, restricts the list of
129+ returned tasks to those that are in one of these states.
130+ :param notag_only: If True, only include tasks without tags. Defaults
131+ to False.
132+ :param started_only: If True, only include tasks that have been
133+ started. That is, tasks that have an already-passed start date or
134+ tasks with no startdate. Defaults to 'True'.
135+ :param is_root: If True, only include tasks that have no parent in the
136+ current selection. Defaults to False.
137+
138+ :return: A list of task ids (tids).
139+ """
140 l_tasks = []
141- for tid in self.ds.all_tasks() :
142+ for tid in self.ds.all_tasks():
143 task = self.get_task(tid)
144- if task and not task.is_loaded() :
145- task = None
146- #This is status filtering
147- if task and not task.get_status() in status :
148- task = None
149- #This is tag filtering
150- #If we still have a task and we need to filter tags
151- #(if tags is None, this test is skipped)
152- if task and tags :
153- if not task.has_tags(tags) :
154- task = None
155- #Checking here the is_root because it has sense only with tags
156- elif is_root and task.has_parents(tag=tags) :
157- task = None
158- #If tags = [], we still check the is_root
159- elif task and is_root :
160- if task.has_parents() :
161- #We accept children of a note
162- for p in task.get_parents() :
163+ if task and not task.is_loaded():
164+ task = None
165+ # This is status filtering.
166+ if task and not task.get_status() in status:
167+ task = None
168+ # This is tag filtering.
169+ # If we still have a task and we need to filter tags
170+ # (if tags is None, this test is skipped)
171+ if task and tags:
172+ if not task.has_tags(tags):
173+ task = None
174+ # Checking here the is_root because it has sense only with
175+ # tags.
176+ elif is_root and task.has_parents(tag=tags):
177+ task = None
178+ #If tags = [], we still check the is_root.
179+ elif task and is_root:
180+ if task.has_parents():
181+ # We accept children of a note.
182+ for p in task.get_parents():
183 pp = self.get_task(p)
184- if pp.get_status() != "Note" :
185+ if pp.get_status() != "Note":
186 task = None
187- #Now checking if it has no tag
188- if task and notag_only :
189- if not task.has_tags(notag_only=notag_only) :
190- task = None
191- #This is started filtering
192- if task and started_only :
193- if not task.is_started() :
194- task = None
195-
196- #If we still have a task, we return it
197- if task :
198+ # Now checking if it has no tag.
199+ if task and notag_only:
200+ if not task.has_tags(notag_only=notag_only):
201+ task = None
202+ # This is started filtering.
203+ if task and started_only:
204+ if not task.is_started():
205+ task = None
206+
207+ # If we still have a task, we return it.
208+ if task:
209 l_tasks.append(tid)
210 return l_tasks
211-
212- #Workable means that the task have no pending subtasks and can be done directly
213- #It also means that all tags are to be "workview" tags (which is the default for tags)
214- #Except if the tag is explicitely selected
215- def get_active_tasks_list(self,tags=None,notag_only=False,\
216- started_only=True,is_root=False,workable=False) :
217+
218+ def get_active_tasks_list(self, tags=None, notag_only=False,
219+ started_only=True, is_root=False,
220+ workable=False):
221+ """Return a list of task ids for all active tasks.
222+
223+ See `get_tasks_list` for more information about the parameters.
224+
225+ :param workable: If True, then only include tasks with no pending
226+ subtasks and that can be done directly and exclude any tasks that
227+ have a 'nonworkview' tag which is not explicitly provided in the
228+ 'tags' parameter. Defaults to False.
229+ """
230 l_tasks = []
231- if workable :
232- nonwork_tag = self.ds.get_tagstore().get_all_tags(\
233- attname="nonworkview",\
234- attvalue="True")
235- #nonwork_tag = []
236- #We build the list of tags we will skip
237- for nwtag in nonwork_tag :
238- #If the tag is explicitely selected, it doesn't go in the
239- #nonwork_tag
240- if tags and nwtag in tags :
241+ if workable:
242+ nonwork_tag = self.ds.get_tagstore().get_all_tags(
243+ attname="nonworkview", attvalue="True")
244+ # We build the list of tags we will skip.
245+ for nwtag in nonwork_tag:
246+ # If the tag is explicitly selected, it doesn't go in the
247+ # nonwork_tag.
248+ if tags and nwtag in tags:
249 nonwork_tag.remove(nwtag)
250- #We build the task list
251- temp_tasks = self.get_active_tasks_list(tags=tags, notag_only=notag_only,\
252- started_only=True,is_root=False,workable=False)
253- #Now we verify that the tasks are workable and doesn't have
254- #a nonwork_tag.
255- for tid in temp_tasks :
256+ # We build the task list.
257+ temp_tasks = self.get_active_tasks_list(
258+ tags=tags, notag_only=notag_only, started_only=True,
259+ is_root=False, workable=False)
260+ # Now we verify that the tasks are workable and don't have a
261+ # nonwork_tag.
262+ for tid in temp_tasks:
263 t = self.get_task(tid)
264- if t and t.is_workable() :
265- if len(nonwork_tag) == 0 :
266+ if t and t.is_workable():
267+ if len(nonwork_tag) == 0:
268 l_tasks.append(tid)
269- elif not t.has_tags(nonwork_tag) :
270+ elif not t.has_tags(nonwork_tag):
271 l_tasks.append(tid)
272 return l_tasks
273- else :
274+ else:
275 active = ["Active"]
276- temp_tasks = self.get_tasks_list(tags=tags,status=active,\
277- notag_only=notag_only,started_only=started_only,is_root=is_root)
278- for t in temp_tasks :
279+ temp_tasks = self.get_tasks_list(
280+ tags=tags, status=active, notag_only=notag_only,
281+ started_only=started_only, is_root=is_root)
282+ for t in temp_tasks:
283 l_tasks.append(t)
284 return l_tasks
285-
286- def get_closed_tasks_list(self,tags=None,notag_only=False,\
287- started_only=False,is_root=False) :
288- closed = ["Done","Dismiss","Deleted"]
289- return self.get_tasks_list(tags=tags,status=closed,\
290- notag_only=notag_only,started_only=started_only,is_root=is_root)
291-
292- def get_notes_list(self,tags=None,notag_only=False) :
293+
294+ def get_closed_tasks_list(self, tags=None, notag_only=False,
295+ started_only=False, is_root=False):
296+ """Return a list of task ids for closed tasks.
297+
298+ "Closed" means either "done", "dismissed" or "deleted".
299+
300+ See `get_tasks_list` for more information about the parameters.
301+ """
302+ closed = ["Done", "Dismiss", "Deleted"]
303+ return self.get_tasks_list(
304+ tags=tags, status=closed, notag_only=notag_only,
305+ started_only=started_only, is_root=is_root)
306+
307+ def get_notes_list(self, tags=None, notag_only=False):
308+ """Return a list of task ids for notes.
309+
310+ See `get_tasks_list` for more information about the parameters.
311+ """
312 note = ["Note"]
313- return self.get_tasks_list(tags=tags,status=note,\
314- notag_only=notag_only,started_only=False,is_root=False)
315-
316-
317-
318+ return self.get_tasks_list(
319+ tags=tags, status=note, notag_only=notag_only, started_only=False,
320+ is_root=False)
321+
322+
323 ############### Tags ##########################
324- ###############################################
325-
326- #MODIFICATION
327- def new_tag(self,tagname) :
328+ ###############################################
329+
330+ def new_tag(self, tagname):
331+ """Create a new tag called 'tagname'.
332+
333+ Note: this modifies the datastore.
334+
335+ :param tagname: The name of the new tag.
336+ :return: The newly-created tag.
337+ """
338 return self.ds.get_tagstore().new_tag(tagname)
339-
340- def get_tag(self,tagname) :
341+
342+ def get_tag(self, tagname):
343 return self.ds.get_tagstore().get_tag(tagname)
344-
345- #Not used currently because it returns every tag that was ever used
346+
347 def get_all_tags(self):
348+ """Return a list of every tag that was ever used."""
349+ # XXX: Not actually used.
350 return returnlist(self.ds.get_tagstore().get_all_tags())
351-
352- def get_notag_tag(self) :
353+
354+ def get_notag_tag(self):
355 return self.ds.get_tagstore().get_notag_tag()
356- def get_alltag_tag(self) :
357+
358+ def get_alltag_tag(self):
359 return self.ds.get_tagstore().get_alltag_tag()
360-
361-
362- #return only tags that are currently used in a task
363- #FIXME it should be only active and visible tasks
364- def get_used_tags(self) :
365+
366+ def get_used_tags(self):
367+ """Return tags currently used by a task.
368+
369+ :return: A list of tags used by a task.
370+ """
371+ # FIXME: it should be only active and visible tasks.
372 l = []
373 for tid in self.ds.all_tasks():
374 t = self.get_task(tid)
375- if t :
376- for tag in t.get_tags() :
377- if tag not in l: l.append(tag)
378+ if t:
379+ for tag in t.get_tags():
380+ if tag not in l:
381+ l.append(tag)
382 return l
383-

Subscribers

People subscribed via source and target branches

to status/vote changes: