Define Comment for representing bug comments.
Comments are a notes that attach to Bugs in threaded trees. In mailing-list terms, a comment is analogous to a single part of an email.
>>> c = Comment()
>>> c.uuid != None
True
>>> c.uuid = "some-UUID"
>>> print c.content_type
text/plain
Methods
| add_reply(reply[, allow_time_inversion]) | |
| append | L.append(object) – append object to end |
| branch_len() | Return the largest number of nodes from root to leaf (inclusive). |
| clear_cached_setting([setting]) | If setting=None, clear all cached settings |
| comment_from_uuid(uuid[, match_alt_id]) | Use a uuid to look up a comment. |
| count(...) | |
| extend | L.extend(iterable) – extend list by appending elements from the iterable |
| from_xml(xml_string[, preserve_uuids, verbose]) | Note: If alt-id is not given, translates any <uuid> fields to |
| has_descendant(descendant[, depth_first, ...]) | Check if a node is contained in a tree. |
| index((value, [start, ...) | Raises ValueError if the value is not present. |
| insert | L.insert(index, object) – insert object before index |
| load_settings([settings_mapfile]) | |
| merge(other[, accept_changes, ...]) | Merge info from other into this comment. |
| new_reply([body, content_type]) | >>> comm = Comment(bug=None, body="Some insightful remarks")
|
| pop(...) | Raises IndexError if list is empty or index is out of range. |
| remove() | |
| reverse | L.reverse() – reverse IN PLACE |
| safe_in_reply_to() | Return self.in_reply_to, except... |
| save() | Save any loaded contents to storage. |
| save_settings() | |
| sibling_uuids() | |
| sort(*args, **kwargs) | Sort the tree recursively. |
| string([indent]) | >>> comm = Comment(bug=None, body="Some\ninsightful\nremarks\n")
|
| string_thread([string_method_name, indent, ...]) | Return a string displaying a thread of comments. |
| thread([flatten]) | Generate a (depth, node) tuple for every node in the tree. |
| traverse(*args, **kwargs) | Avoid working with the possible dummy root comment |
| xml([indent]) | >>> comm = Comment(bug=None, body="Some\ninsightful\nremarks\n")
|
| xml_thread([indent]) |
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.
This property defaults to None.
The author of the comment
This property defaults to None.
The meat of the comment
Use a uuid to look up a comment.
>>> a = Comment(bug=None, uuid="a")
>>> b = a.new_reply()
>>> b.uuid = "b"
>>> c = b.new_reply()
>>> c.uuid = "c"
>>> d = a.new_reply()
>>> d.uuid = "d"
>>> d.alt_id = "d-alt"
>>> comm = a.comment_from_uuid("d")
>>> id(comm) == id(d)
True
>>> comm = a.comment_from_uuid("d-alt")
>>> id(comm) == id(d)
True
>>> comm = a.comment_from_uuid(None, match_alt_id=False)
Traceback (most recent call last):
...
KeyError: None
Mime type for comment body
This property defaults to text/plain.
An RFC 2822 timestamp for comment creation
This property defaults to None.
Space for an array of extra strings. Useful for storing state for functionality implemented purely in becommands/<some_function>.py.
This property defaults to [].
This property is checked with <function _extra_strings_check_fn at 0x95900d4>.
Note: If alt-id is not given, translates any <uuid> fields to <alt-id> fields. >>> commA = Comment(bug=None, body=”Someninsightfulnremarksn”) >>> commA.uuid = “0123” >>> commA.date = “Thu, 01 Jan 1970 00:00:00 +0000” >>> commA.author = u’François’ >>> commA.extra_strings += [‘TAG: very helpful’] >>> xml = commA.xml() >>> commB = Comment() >>> commB.from_xml(xml, verbose=True) >>> commB.explicit_attrs [‘author’, ‘date’, ‘content_type’, ‘body’, ‘alt_id’] >>> commB.xml() == xml False >>> commB.uuid = commB.alt_id >>> commB.alt_id = None >>> commB.xml() == xml True >>> commC = Comment() >>> commC.from_xml(xml, preserve_uuids=True) >>> commC.uuid == commA.uuid True
UUID for parent comment or bug
This property defaults to None.
Merge info from other into this comment. Overrides any attributes in self that are listed in other.explicit_attrs.
>>> commA = Comment(bug=None, body='Some insightful remarks')
>>> commA.uuid = '0123'
>>> commA.date = 'Thu, 01 Jan 1970 00:00:00 +0000'
>>> commA.author = 'Frank'
>>> commA.extra_strings += ['TAG: very helpful']
>>> commA.extra_strings += ['TAG: favorite']
>>> commB = Comment(bug=None, body='More insightful remarks')
>>> commB.uuid = '3210'
>>> commB.date = 'Fri, 02 Jan 1970 00:00:00 +0000'
>>> commB.author = 'John'
>>> commB.explicit_attrs = ['author', 'body']
>>> commB.extra_strings += ['TAG: very helpful']
>>> commB.extra_strings += ['TAG: useful']
>>> commA.merge(commB, accept_changes=False,
... accept_extra_strings=False, change_exception=False)
>>> commA.merge(commB, accept_changes=False,
... accept_extra_strings=False, change_exception=True)
Traceback (most recent call last):
...
ValueError: Merge would change author "Frank"->"John" for comment 0123
>>> commA.merge(commB, accept_changes=True,
... accept_extra_strings=False, change_exception=True)
Traceback (most recent call last):
...
ValueError: Merge would add extra string "TAG: useful" to comment 0123
>>> print commA.author
John
>>> print commA.extra_strings
['TAG: favorite', 'TAG: very helpful']
>>> commA.merge(commB, accept_changes=True,
... accept_extra_strings=True, change_exception=True)
>>> print commA.extra_strings
['TAG: favorite', 'TAG: useful', 'TAG: very helpful']
>>> print commA.xml()
<comment>
<uuid>0123</uuid>
<short-name>//012</short-name>
<author>John</author>
<date>Thu, 01 Jan 1970 00:00:00 +0000</date>
<content-type>text/plain</content-type>
<body>More insightful remarks</body>
<extra-string>TAG: favorite</extra-string>
<extra-string>TAG: useful</extra-string>
<extra-string>TAG: very helpful</extra-string>
</comment>
>>> comm = Comment(bug=None, body="Some insightful remarks")
>>> repA = comm.new_reply("Critique original comment")
>>> repB = repA.new_reply("Begin flamewar :p")
>>> repB.in_reply_to == repA.uuid
True
Return self.in_reply_to, except...
Save any loaded contents to storage.
However, if self.storage.is_writeable() == True, then any changes are automatically written to storage as soon as they happen, so calling this method will just waste time (unless something else has been messing with your stored files).
>>> comm = Comment(bug=None, body="Some\ninsightful\nremarks\n")
>>> comm.uuid = 'abcdef'
>>> comm.date = "Thu, 01 Jan 1970 00:00:00 +0000"
>>> print comm.string(indent=2)
--------- Comment ---------
Name: //abc
From:
Date: Thu, 01 Jan 1970 00:00:00 +0000
Some
insightful
remarks
Return a string displaying a thread of comments. bug_shortname is only used if auto_name_map == True.
string_method_name (defaults to “string”) is the name of the Comment method used to generate the output string for each Comment in the thread. The method must take the arguments indent and shortname.
>>> a = Comment(bug=None, uuid="a", body="Insightful remarks")
>>> a.time = utility.str_to_time("Thu, 20 Nov 2008 01:00:00 +0000")
>>> b = a.new_reply("Critique original comment")
>>> b.uuid = "b"
>>> b.time = utility.str_to_time("Thu, 20 Nov 2008 02:00:00 +0000")
>>> c = b.new_reply("Begin flamewar :p")
>>> c.uuid = "c"
>>> c.time = utility.str_to_time("Thu, 20 Nov 2008 03:00:00 +0000")
>>> d = a.new_reply("Useful examples")
>>> d.uuid = "d"
>>> d.time = utility.str_to_time("Thu, 20 Nov 2008 04:00:00 +0000")
>>> a.sort(key=lambda comm : comm.time)
>>> print a.string_thread(flatten=True)
--------- Comment ---------
Name: //a
From:
Date: Thu, 20 Nov 2008 01:00:00 +0000
Insightful remarks
--------- Comment ---------
Name: //b
From:
Date: Thu, 20 Nov 2008 02:00:00 +0000
Critique original comment
--------- Comment ---------
Name: //c
From:
Date: Thu, 20 Nov 2008 03:00:00 +0000
Begin flamewar :p
--------- Comment ---------
Name: //d
From:
Date: Thu, 20 Nov 2008 04:00:00 +0000
Useful examples
>>> print a.string_thread()
--------- Comment ---------
Name: //a
From:
Date: Thu, 20 Nov 2008 01:00:00 +0000
Insightful remarks
--------- Comment ---------
Name: //b
From:
Date: Thu, 20 Nov 2008 02:00:00 +0000
Critique original comment
--------- Comment ---------
Name: //c
From:
Date: Thu, 20 Nov 2008 03:00:00 +0000
Begin flamewar :p
--------- Comment ---------
Name: //d
From:
Date: Thu, 20 Nov 2008 04:00:00 +0000
Useful examples
An integer version of .date
Avoid working with the possible dummy root comment
>>> comm = Comment(bug=None, body="Some\ninsightful\nremarks\n")
>>> comm.uuid = "0123"
>>> comm.date = "Thu, 01 Jan 1970 00:00:00 +0000"
>>> print comm.xml(indent=2)
<comment>
<uuid>0123</uuid>
<short-name>//012</short-name>
<author></author>
<date>Thu, 01 Jan 1970 00:00:00 +0000</date>
<content-type>text/plain</content-type>
<body>Some
insightful
remarks</body>
</comment>
>>> comm.content_type = 'image/png'
>>> print comm.xml()
<comment>
<uuid>0123</uuid>
<short-name>//012</short-name>
<author></author>
<date>Thu, 01 Jan 1970 00:00:00 +0000</date>
<content-type>image/png</content-type>
<body>U29tZQppbnNpZ2h0ZnVsCnJlbWFya3MK
</body>
</comment>
Compare a general attribute between two comments using the conventional comparison rule for that attribute type. If invert == True, sort against that convention.
>>> attr="author"
>>> commentA = Comment()
>>> commentB = Comment()
>>> commentA.author = "John Doe"
>>> commentB.author = "Jane Doe"
>>> cmp_attr(commentA, commentB, attr) > 0
True
>>> cmp_attr(commentA, commentB, attr, invert=True) < 0
True
>>> commentB.author = "John Doe"
>>> cmp_attr(commentA, commentB, attr) == 0
True
Set load_full=True when you want to load the comment completely from disk now, rather than waiting and lazy loading as required.