Remove old exception types from libbe.bug and libbe.comment.
[be.git] / libbe / comment.py
1 # Copyright (C) 2008-2011 Gianluca Montecchi <gian@grys.it>
2 #                         Thomas Habets <thomas@habets.pp.se>
3 #                         W. Trevor King <wking@drexel.edu>
4 #
5 # This file is part of Bugs Everywhere.
6 #
7 # Bugs Everywhere is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by the
9 # Free Software Foundation, either version 2 of the License, or (at your
10 # option) any later version.
11 #
12 # Bugs Everywhere is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 # General Public License for more details.
16 #
17 # You should have received a copy of the GNU General Public License
18 # along with Bugs Everywhere.  If not, see <http://www.gnu.org/licenses/>.
19
20 """Define the :class:`Comment` class for representing bug comments.
21 """
22
23 import base64
24 import os
25 import os.path
26 import sys
27 import time
28 import types
29 try:
30     from email.mime.base import MIMEBase
31     from email.encoders import encode_base64
32 except ImportError:
33     # adjust to old python 2.4
34     from email.MIMEBase import MIMEBase
35     from email.Encoders import encode_base64
36 try: # import core module, Python >= 2.5
37     from xml.etree import ElementTree
38 except ImportError: # look for non-core module
39     from elementtree import ElementTree
40 import xml.sax.saxutils
41
42 import libbe
43 import libbe.util.id
44 from libbe.storage.util.properties import Property, doc_property, \
45     local_property, defaulting_property, checked_property, cached_property, \
46     primed_property, change_hook_property, settings_property
47 import libbe.storage.util.settings_object as settings_object
48 import libbe.storage.util.mapfile as mapfile
49 from libbe.util.tree import Tree
50 import libbe.util.utility as utility
51
52 if libbe.TESTING == True:
53     import doctest
54
55
56 class MissingReference(ValueError):
57     def __init__(self, comment):
58         msg = "Missing reference to %s" % (comment.in_reply_to)
59         ValueError.__init__(self, msg)
60         self.reference = comment.in_reply_to
61         self.comment = comment
62
63 INVALID_UUID = "!!~~\n INVALID-UUID \n~~!!"
64
65 def load_comments(bug, load_full=False):
66     """
67     Set load_full=True when you want to load the comment completely
68     from disk *now*, rather than waiting and lazy loading as required.
69     """
70     uuids = []
71     for id in libbe.util.id.child_uuids(
72                   bug.storage.children(
73                       bug.id.storage())):
74         uuids.append(id)
75     comments = []
76     for uuid in uuids:
77         comm = Comment(bug, uuid, from_storage=True)
78         if load_full == True:
79             comm.load_settings()
80             dummy = comm.body # force the body to load
81         comments.append(comm)
82     bug.comment_root = Comment(bug, uuid=INVALID_UUID)
83     bug.add_comments(comments, ignore_missing_references=True)
84     return bug.comment_root
85
86 def save_comments(bug):
87     for comment in bug.comment_root.traverse():
88         comment.save()
89
90
91 class Comment (Tree, settings_object.SavedSettingsObject):
92     """Comments are a notes that attach to :class:`~libbe.bug.Bug`\s in
93     threaded trees.  In mailing-list terms, a comment is analogous to
94     a single part of an email.
95
96     >>> c = Comment()
97     >>> c.uuid != None
98     True
99     >>> c.uuid = "some-UUID"
100     >>> print c.content_type
101     text/plain
102     """
103
104     settings_properties = []
105     required_saved_properties = []
106     _prop_save_settings = settings_object.prop_save_settings
107     _prop_load_settings = settings_object.prop_load_settings
108     def _versioned_property(settings_properties=settings_properties,
109                             required_saved_properties=required_saved_properties,
110                             **kwargs):
111         if "settings_properties" not in kwargs:
112             kwargs["settings_properties"] = settings_properties
113         if "required_saved_properties" not in kwargs:
114             kwargs["required_saved_properties"]=required_saved_properties
115         return settings_object.versioned_property(**kwargs)
116
117     @_versioned_property(name="Alt-id",
118                          doc="Alternate ID for linking imported comments.  Internally comments are linked (via In-reply-to) to the parent's UUID.  However, these UUIDs are generated internally, so Alt-id is provided as a user-controlled linking target.")
119     def alt_id(): return {}
120
121     @_versioned_property(name="Author",
122                          doc="The author of the comment")
123     def author(): return {}
124
125     @_versioned_property(name="In-reply-to",
126                          doc="UUID for parent comment or bug")
127     def in_reply_to(): return {}
128
129     @_versioned_property(name="Content-type",
130                          doc="Mime type for comment body",
131                          default="text/plain",
132                          require_save=True)
133     def content_type(): return {}
134
135     @_versioned_property(name="Date",
136                          doc="An RFC 2822 timestamp for comment creation")
137     def date(): return {}
138
139     def _get_time(self):
140         if self.date == None:
141             return None
142         return utility.str_to_time(self.date)
143     def _set_time(self, value):
144         self.date = utility.time_to_str(value)
145     time = property(fget=_get_time,
146                     fset=_set_time,
147                     doc="An integer version of .date")
148
149     def _get_comment_body(self):
150         if self.storage != None and self.storage.is_readable() \
151                 and self.uuid != INVALID_UUID:
152             return self.storage.get(self.id.storage("body"),
153                 decode=self.content_type.startswith("text/"))
154     def _set_comment_body(self, old=None, new=None, force=False):
155         assert self.uuid != INVALID_UUID, self
156         if self.content_type.startswith('text/') \
157                 and self.bug != None and self.bug.bugdir != None:
158             new = libbe.util.id.short_to_long_text([self.bug.bugdir], new)
159         if (self.storage != None and self.storage.writeable == True) \
160                 or force==True:
161             assert new != None, "Can't save empty comment"
162             self.storage.set(self.id.storage("body"), new)
163
164     @Property
165     @change_hook_property(hook=_set_comment_body)
166     @cached_property(generator=_get_comment_body)
167     @local_property("body")
168     @doc_property(doc="The meat of the comment")
169     def body(): return {}
170
171     def _extra_strings_check_fn(value):
172         return utility.iterable_full_of_strings(value, \
173                          alternative=settings_object.EMPTY)
174     def _extra_strings_change_hook(self, old, new):
175         self.extra_strings.sort() # to make merging easier
176         self._prop_save_settings(old, new)
177     @_versioned_property(name="extra_strings",
178                          doc="Space for an array of extra strings.  Useful for storing state for functionality implemented purely in becommands/<some_function>.py.",
179                          default=[],
180                          check_fn=_extra_strings_check_fn,
181                          change_hook=_extra_strings_change_hook,
182                          mutable=True)
183     def extra_strings(): return {}
184
185     def __init__(self, bug=None, uuid=None, from_storage=False,
186                  in_reply_to=None, body=None, content_type=None):
187         """
188         Set ``from_storage=True`` to load an old comment.
189         Set ``from_storage=False`` to create a new comment.
190
191         The ``uuid`` option is required when ``from_storage==True``.
192
193         The in_reply_to, body, and content_type options are only used
194         if ``from_storage==False`` (the default).  When
195         ``from_storage==True``, they are loaded from the bug database.
196         ``content_type`` decides if the body should be run through
197         :func:`util.id.short_to_long_text` before saving.  See
198         :meth:`_set_comment_body` for details.
199
200         ``in_reply_to`` should be the uuid string of the parent comment.
201         """
202         Tree.__init__(self)
203         settings_object.SavedSettingsObject.__init__(self)
204         self.bug = bug
205         self.storage = None
206         self.uuid = uuid
207         self.id = libbe.util.id.ID(self, 'comment')
208         if from_storage == False:
209             if uuid == None:
210                 self.uuid = libbe.util.id.uuid_gen()
211             self.time = int(time.time()) # only save to second precision
212             self.in_reply_to = in_reply_to
213             if content_type != None:
214                 self.content_type = content_type
215             self.body = body
216         if self.bug != None:
217             self.storage = self.bug.storage
218         if from_storage == False:
219             if self.storage != None and self.storage.is_writeable():
220                 self.save()
221
222     def __cmp__(self, other):
223         return cmp_full(self, other)
224
225     def __str__(self):
226         """
227         >>> comm = Comment(bug=None, body="Some insightful remarks")
228         >>> comm.uuid = "com-1"
229         >>> comm.date = "Thu, 20 Nov 2008 15:55:11 +0000"
230         >>> comm.author = "Jane Doe <jdoe@example.com>"
231         >>> print comm
232         --------- Comment ---------
233         Name: //com
234         From: Jane Doe <jdoe@example.com>
235         Date: Thu, 20 Nov 2008 15:55:11 +0000
236         <BLANKLINE>
237         Some insightful remarks
238         """
239         return self.string()
240
241     def traverse(self, *args, **kwargs):
242         """Avoid working with the possible dummy root comment"""
243         for comment in Tree.traverse(self, *args, **kwargs):
244             if comment.uuid == INVALID_UUID:
245                 continue
246             yield comment
247
248     # serializing methods
249
250     def _setting_attr_string(self, setting):
251         value = getattr(self, setting)
252         if value == None:
253             return ""
254         if type(value) not in types.StringTypes:
255             return str(value)
256         return value
257
258     def safe_in_reply_to(self):
259         """
260         Return self.in_reply_to, except...
261
262           * if no comment matches that id, in which case return None.
263           * if that id matches another comments .alt_id, in which case
264             return the matching comments .uuid.
265         """
266         if self.in_reply_to == None:
267             return None
268         else:
269             try:
270                 irt_comment = self.bug.comment_from_uuid(
271                     self.in_reply_to, match_alt_id=True)
272                 return irt_comment.uuid
273             except KeyError:
274                 return None
275
276     def xml(self, indent=0):
277         """
278         >>> comm = Comment(bug=None, body="Some\\ninsightful\\nremarks\\n")
279         >>> comm.uuid = "0123"
280         >>> comm.date = "Thu, 01 Jan 1970 00:00:00 +0000"
281         >>> print comm.xml(indent=2)
282           <comment>
283             <uuid>0123</uuid>
284             <short-name>//012</short-name>
285             <author></author>
286             <date>Thu, 01 Jan 1970 00:00:00 +0000</date>
287             <content-type>text/plain</content-type>
288             <body>Some
289         insightful
290         remarks</body>
291           </comment>
292         >>> comm.content_type = 'image/png'
293         >>> print comm.xml()
294         <comment>
295           <uuid>0123</uuid>
296           <short-name>//012</short-name>
297           <author></author>
298           <date>Thu, 01 Jan 1970 00:00:00 +0000</date>
299           <content-type>image/png</content-type>
300           <body>U29tZQppbnNpZ2h0ZnVsCnJlbWFya3MK
301         </body>
302         </comment>
303         """
304         if self.content_type.startswith('text/'):
305             body = (self.body or '').rstrip('\n')
306         else:
307             maintype,subtype = self.content_type.split('/',1)
308             msg = MIMEBase(maintype, subtype)
309             msg.set_payload(self.body or '')
310             encode_base64(msg)
311             body = base64.encodestring(self.body or '')
312         info = [('uuid', self.uuid),
313                 ('alt-id', self.alt_id),
314                 ('short-name', self.id.user()),
315                 ('in-reply-to', self.safe_in_reply_to()),
316                 ('author', self._setting_attr_string('author')),
317                 ('date', self.date),
318                 ('content-type', self.content_type),
319                 ('body', body)]
320         lines = ['<comment>']
321         for (k,v) in info:
322             if v != None:
323                 lines.append('  <%s>%s</%s>' % (k,xml.sax.saxutils.escape(v),k))
324         for estr in self.extra_strings:
325             lines.append('  <extra-string>%s</extra-string>' % estr)
326         lines.append('</comment>')
327         istring = ' '*indent
328         sep = '\n' + istring
329         return istring + sep.join(lines).rstrip('\n')
330
331     def from_xml(self, xml_string, preserve_uuids=False, verbose=True):
332         u"""
333         Note: If alt-id is not given, translates any <uuid> fields to
334         <alt-id> fields.
335         >>> commA = Comment(bug=None, body="Some\\ninsightful\\nremarks\\n")
336         >>> commA.uuid = "0123"
337         >>> commA.date = "Thu, 01 Jan 1970 00:00:00 +0000"
338         >>> commA.author = u'Fran\xe7ois'
339         >>> commA.extra_strings += ['TAG: very helpful']
340         >>> xml = commA.xml()
341         >>> commB = Comment()
342         >>> commB.from_xml(xml, verbose=True)
343         >>> commB.explicit_attrs
344         ['author', 'date', 'content_type', 'body', 'alt_id']
345         >>> commB.xml() == xml
346         False
347         >>> commB.uuid = commB.alt_id
348         >>> commB.alt_id = None
349         >>> commB.xml() == xml
350         True
351         >>> commC = Comment()
352         >>> commC.from_xml(xml, preserve_uuids=True)
353         >>> commC.uuid == commA.uuid
354         True
355         """
356         if type(xml_string) == types.UnicodeType:
357             xml_string = xml_string.strip().encode('unicode_escape')
358         if hasattr(xml_string, 'getchildren'): # already an ElementTree Element
359             comment = xml_string
360         else:
361             comment = ElementTree.XML(xml_string)
362         if comment.tag != 'comment':
363             raise utility.InvalidXML( \
364                 'comment', comment, 'root element must be <comment>')
365         tags=['uuid','alt-id','in-reply-to','author','date','content-type',
366               'body','extra-string']
367         self.explicit_attrs = []
368         uuid = None
369         body = None
370         estrs = []
371         for child in comment.getchildren():
372             if child.tag == 'short-name':
373                 pass
374             elif child.tag in tags:
375                 if child.text == None or len(child.text) == 0:
376                     text = settings_object.EMPTY
377                 else:
378                     text = xml.sax.saxutils.unescape(child.text)
379                     text = text.decode('unicode_escape').strip()
380                 if child.tag == 'uuid' and not preserve_uuids:
381                     uuid = text
382                     continue # don't set the comment's uuid tag.
383                 elif child.tag == 'body':
384                     body = text
385                     self.explicit_attrs.append(child.tag)
386                     continue # don't set the comment's body yet.
387                 elif child.tag == 'extra-string':
388                     estrs.append(text)
389                     continue # don't set the comment's extra_string yet.
390                 attr_name = child.tag.replace('-','_')
391                 self.explicit_attrs.append(attr_name)
392                 setattr(self, attr_name, text)
393             elif verbose == True:
394                 print >> sys.stderr, 'Ignoring unknown tag %s in %s' \
395                     % (child.tag, comment.tag)
396         if uuid != self.uuid and self.alt_id == None:
397             self.explicit_attrs.append('alt_id')
398             self.alt_id = uuid
399         if body != None:
400             if self.content_type.startswith('text/'):
401                 self.body = body+'\n' # restore trailing newline
402             else:
403                 self.body = base64.decodestring(body)
404         self.extra_strings = estrs
405
406     def merge(self, other, accept_changes=True,
407               accept_extra_strings=True, change_exception=False):
408         """
409         Merge info from other into this comment.  Overrides any
410         attributes in self that are listed in other.explicit_attrs.
411
412         >>> commA = Comment(bug=None, body='Some insightful remarks')
413         >>> commA.uuid = '0123'
414         >>> commA.date = 'Thu, 01 Jan 1970 00:00:00 +0000'
415         >>> commA.author = 'Frank'
416         >>> commA.extra_strings += ['TAG: very helpful']
417         >>> commA.extra_strings += ['TAG: favorite']
418         >>> commB = Comment(bug=None, body='More insightful remarks')
419         >>> commB.uuid = '3210'
420         >>> commB.date = 'Fri, 02 Jan 1970 00:00:00 +0000'
421         >>> commB.author = 'John'
422         >>> commB.explicit_attrs = ['author', 'body']
423         >>> commB.extra_strings += ['TAG: very helpful']
424         >>> commB.extra_strings += ['TAG: useful']
425         >>> commA.merge(commB, accept_changes=False,
426         ...             accept_extra_strings=False, change_exception=False)
427         >>> commA.merge(commB, accept_changes=False,
428         ...             accept_extra_strings=False, change_exception=True)
429         Traceback (most recent call last):
430           ...
431         ValueError: Merge would change author "Frank"->"John" for comment 0123
432         >>> commA.merge(commB, accept_changes=True,
433         ...             accept_extra_strings=False, change_exception=True)
434         Traceback (most recent call last):
435           ...
436         ValueError: Merge would add extra string "TAG: useful" to comment 0123
437         >>> print commA.author
438         John
439         >>> print commA.extra_strings
440         ['TAG: favorite', 'TAG: very helpful']
441         >>> commA.merge(commB, accept_changes=True,
442         ...             accept_extra_strings=True, change_exception=True)
443         >>> print commA.extra_strings
444         ['TAG: favorite', 'TAG: useful', 'TAG: very helpful']
445         >>> print commA.xml()
446         <comment>
447           <uuid>0123</uuid>
448           <short-name>//012</short-name>
449           <author>John</author>
450           <date>Thu, 01 Jan 1970 00:00:00 +0000</date>
451           <content-type>text/plain</content-type>
452           <body>More insightful remarks</body>
453           <extra-string>TAG: favorite</extra-string>
454           <extra-string>TAG: useful</extra-string>
455           <extra-string>TAG: very helpful</extra-string>
456         </comment>
457         """
458         for attr in other.explicit_attrs:
459             old = getattr(self, attr)
460             new = getattr(other, attr)
461             if old != new:
462                 if accept_changes == True:
463                     setattr(self, attr, new)
464                 elif change_exception == True:
465                     raise ValueError, \
466                         'Merge would change %s "%s"->"%s" for comment %s' \
467                         % (attr, old, new, self.uuid)
468         if self.alt_id == self.uuid:
469             self.alt_id = None
470         for estr in other.extra_strings:
471             if not estr in self.extra_strings:
472                 if accept_extra_strings == True:
473                     self.extra_strings.append(estr)
474                 elif change_exception == True:
475                     raise ValueError, \
476                         'Merge would add extra string "%s" to comment %s' \
477                         % (estr, self.uuid)
478
479     def string(self, indent=0):
480         """
481         >>> comm = Comment(bug=None, body="Some\\ninsightful\\nremarks\\n")
482         >>> comm.uuid = 'abcdef'
483         >>> comm.date = "Thu, 01 Jan 1970 00:00:00 +0000"
484         >>> print comm.string(indent=2)
485           --------- Comment ---------
486           Name: //abc
487           From: 
488           Date: Thu, 01 Jan 1970 00:00:00 +0000
489         <BLANKLINE>
490           Some
491           insightful
492           remarks
493         """
494         lines = []
495         lines.append("--------- Comment ---------")
496         lines.append("Name: %s" % self.id.user())
497         lines.append("From: %s" % (self._setting_attr_string("author")))
498         lines.append("Date: %s" % self.date)
499         lines.append("")
500         if self.content_type.startswith("text/"):
501             body = (self.body or "")
502             if self.bug != None and self.bug.bugdir != None:
503                 body = libbe.util.id.long_to_short_text([self.bug.bugdir], body)
504             lines.extend(body.splitlines())
505         else:
506             lines.append("Content type %s not printable.  Try XML output instead" % self.content_type)
507
508         istring = ' '*indent
509         sep = '\n' + istring
510         return istring + sep.join(lines).rstrip('\n')
511
512     def string_thread(self, string_method_name="string",
513                       indent=0, flatten=True):
514         """
515         Return a string displaying a thread of comments.
516         bug_shortname is only used if auto_name_map == True.
517
518         string_method_name (defaults to "string") is the name of the
519         Comment method used to generate the output string for each
520         Comment in the thread.  The method must take the arguments
521         indent and shortname.
522
523         >>> a = Comment(bug=None, uuid="a", body="Insightful remarks")
524         >>> a.time = utility.str_to_time("Thu, 20 Nov 2008 01:00:00 +0000")
525         >>> b = a.new_reply("Critique original comment")
526         >>> b.uuid = "b"
527         >>> b.time = utility.str_to_time("Thu, 20 Nov 2008 02:00:00 +0000")
528         >>> c = b.new_reply("Begin flamewar :p")
529         >>> c.uuid = "c"
530         >>> c.time = utility.str_to_time("Thu, 20 Nov 2008 03:00:00 +0000")
531         >>> d = a.new_reply("Useful examples")
532         >>> d.uuid = "d"
533         >>> d.time = utility.str_to_time("Thu, 20 Nov 2008 04:00:00 +0000")
534         >>> a.sort(key=lambda comm : comm.time)
535         >>> print a.string_thread(flatten=True)
536         --------- Comment ---------
537         Name: //a
538         From: 
539         Date: Thu, 20 Nov 2008 01:00:00 +0000
540         <BLANKLINE>
541         Insightful remarks
542           --------- Comment ---------
543           Name: //b
544           From: 
545           Date: Thu, 20 Nov 2008 02:00:00 +0000
546         <BLANKLINE>
547           Critique original comment
548           --------- Comment ---------
549           Name: //c
550           From: 
551           Date: Thu, 20 Nov 2008 03:00:00 +0000
552         <BLANKLINE>
553           Begin flamewar :p
554         --------- Comment ---------
555         Name: //d
556         From: 
557         Date: Thu, 20 Nov 2008 04:00:00 +0000
558         <BLANKLINE>
559         Useful examples
560         >>> print a.string_thread()
561         --------- Comment ---------
562         Name: //a
563         From: 
564         Date: Thu, 20 Nov 2008 01:00:00 +0000
565         <BLANKLINE>
566         Insightful remarks
567           --------- Comment ---------
568           Name: //b
569           From: 
570           Date: Thu, 20 Nov 2008 02:00:00 +0000
571         <BLANKLINE>
572           Critique original comment
573           --------- Comment ---------
574           Name: //c
575           From: 
576           Date: Thu, 20 Nov 2008 03:00:00 +0000
577         <BLANKLINE>
578           Begin flamewar :p
579         --------- Comment ---------
580         Name: //d
581         From: 
582         Date: Thu, 20 Nov 2008 04:00:00 +0000
583         <BLANKLINE>
584         Useful examples
585         """
586         stringlist = []
587         for depth,comment in self.thread(flatten=flatten):
588             ind = 2*depth+indent
589             string_fn = getattr(comment, string_method_name)
590             stringlist.append(string_fn(indent=ind))
591         return '\n'.join(stringlist)
592
593     def xml_thread(self, indent=0):
594         return self.string_thread(string_method_name="xml", indent=indent)
595
596     # methods for saving/loading/acessing settings and properties.
597
598     def load_settings(self, settings_mapfile=None):
599         if self.uuid == INVALID_UUID:
600             return
601         if settings_mapfile == None:
602             settings_mapfile = self.storage.get(self.id.storage('values'))
603         try:
604             settings = mapfile.parse(settings_mapfile)
605         except mapfile.InvalidMapfileContents, e:
606             raise Exception('Invalid settings file for comment %s\n'
607                             '(BE version missmatch?)' % self.id.user())
608         self._setup_saved_settings(settings)
609
610     def save_settings(self):
611         if self.uuid == INVALID_UUID:
612             return
613         mf = mapfile.generate(self._get_saved_settings())
614         self.storage.set(self.id.storage("values"), mf)
615
616     def save(self):
617         """
618         Save any loaded contents to storage.
619
620         However, if ``self.storage.is_writeable() == True``, then any
621         changes are automatically written to storage as soon as they
622         happen, so calling this method will just waste time (unless
623         something else has been messing with your stored files).
624         """
625         if self.uuid == INVALID_UUID:
626             return
627         assert self.storage != None, "Can't save without storage"
628         assert self.body != None, "Can't save blank comment"
629         if self.bug != None:
630             parent = self.bug.id.storage()
631         else:
632             parent = None
633         self.storage.add(self.id.storage(), parent=parent, directory=True)
634         self.storage.add(self.id.storage('values'), parent=self.id.storage(),
635                          directory=False)
636         self.storage.add(self.id.storage('body'), parent=self.id.storage(),
637                          directory=False)
638         self.save_settings()
639         self._set_comment_body(new=self.body, force=True)
640
641     def remove(self):
642         for comment in self:
643             comment.remove()
644         if self.uuid != INVALID_UUID:
645             self.storage.recursive_remove(self.id.storage())
646
647     def add_reply(self, reply, allow_time_inversion=False):
648         if self.uuid != INVALID_UUID:
649             reply.in_reply_to = self.uuid
650         self.append(reply)
651
652     def new_reply(self, body=None, content_type=None):
653         """
654         >>> comm = Comment(bug=None, body="Some insightful remarks")
655         >>> repA = comm.new_reply("Critique original comment")
656         >>> repB = repA.new_reply("Begin flamewar :p")
657         >>> repB.in_reply_to == repA.uuid
658         True
659         """
660         reply = Comment(self.bug, body=body, content_type=content_type)
661         self.add_reply(reply)
662         return reply
663
664     def comment_from_uuid(self, uuid, match_alt_id=True):
665         """Use a uuid to look up a comment.
666
667         >>> a = Comment(bug=None, uuid="a")
668         >>> b = a.new_reply()
669         >>> b.uuid = "b"
670         >>> c = b.new_reply()
671         >>> c.uuid = "c"
672         >>> d = a.new_reply()
673         >>> d.uuid = "d"
674         >>> d.alt_id = "d-alt"
675         >>> comm = a.comment_from_uuid("d")
676         >>> id(comm) == id(d)
677         True
678         >>> comm = a.comment_from_uuid("d-alt")
679         >>> id(comm) == id(d)
680         True
681         >>> comm = a.comment_from_uuid(None, match_alt_id=False)
682         Traceback (most recent call last):
683           ...
684         KeyError: None
685         """
686         for comment in self.traverse():
687             if comment.uuid == uuid:
688                 return comment
689             if match_alt_id == True and uuid != None \
690                     and comment.alt_id == uuid:
691                 return comment
692         raise KeyError(uuid)
693
694     # methods for id generation
695
696     def sibling_uuids(self):
697         if self.bug != None:
698             return self.bug.uuids()
699         return []
700
701
702 def cmp_attr(comment_1, comment_2, attr, invert=False):
703     """
704     Compare a general attribute between two comments using the conventional
705     comparison rule for that attribute type.  If invert == True, sort
706     *against* that convention.
707
708     >>> attr="author"
709     >>> commentA = Comment()
710     >>> commentB = Comment()
711     >>> commentA.author = "John Doe"
712     >>> commentB.author = "Jane Doe"
713     >>> cmp_attr(commentA, commentB, attr) > 0
714     True
715     >>> cmp_attr(commentA, commentB, attr, invert=True) < 0
716     True
717     >>> commentB.author = "John Doe"
718     >>> cmp_attr(commentA, commentB, attr) == 0
719     True
720     """
721     if not hasattr(comment_2, attr) :
722         return 1
723     val_1 = getattr(comment_1, attr)
724     val_2 = getattr(comment_2, attr)
725     if val_1 == None: val_1 = None
726     if val_2 == None: val_2 = None
727
728     if invert == True :
729         return -cmp(val_1, val_2)
730     else :
731         return cmp(val_1, val_2)
732
733 # alphabetical rankings (a < z)
734 cmp_uuid = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "uuid")
735 cmp_author = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "author")
736 cmp_in_reply_to = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "in_reply_to")
737 cmp_content_type = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "content_type")
738 cmp_body = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "body")
739 cmp_extra_strings = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "extra_strings")
740 # chronological rankings (newer < older)
741 cmp_time = lambda comment_1, comment_2 : cmp_attr(comment_1, comment_2, "time", invert=True)
742
743
744 DEFAULT_CMP_FULL_CMP_LIST = \
745     (cmp_time, cmp_author, cmp_content_type, cmp_body, cmp_in_reply_to,
746      cmp_uuid, cmp_extra_strings)
747
748 class CommentCompoundComparator (object):
749     def __init__(self, cmp_list=DEFAULT_CMP_FULL_CMP_LIST):
750         self.cmp_list = cmp_list
751     def __call__(self, comment_1, comment_2):
752         for comparison in self.cmp_list :
753             val = comparison(comment_1, comment_2)
754             if val != 0 :
755                 return val
756         return 0
757
758 cmp_full = CommentCompoundComparator()
759
760 if libbe.TESTING == True:
761     suite = doctest.DocTestSuite()