# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-"""Define the Bug class for representing bugs.
+"""Define the :class:`Bug` class for representing bugs.
"""
import copy
class Bug (settings_object.SavedSettingsObject):
"""A bug (or issue) is a place to store attributes and attach
- comments. In mailing-list terms, a bug is analogous to a thread.
+ :class:`libbe.comment.Comment`\s. In mailing-list terms, a bug is
+ analogous to a thread. Bugs are normally stored in
+ :class:`libbe.bugdir.BugDir`\s.
>>> b = Bug()
>>> print b.status
"""
Compare the severity levels of two bugs, with more severe bugs
comparing as less.
+
>>> bugA = Bug()
>>> bugB = Bug()
>>> bugA.severity = bugB.severity = "wishlist"
def cmp_status(bug_1, bug_2):
"""
- Compare the status levels of two bugs, with more 'open' bugs
+ Compare the status levels of two bugs, with more "open" bugs
comparing as less.
+
>>> bugA = Bug()
>>> bugB = Bug()
>>> bugA.status = bugB.status = "open"
def cmp_attr(bug_1, bug_2, attr, invert=False):
"""
- Compare a general attribute between two bugs using the conventional
- comparison rule for that attribute type. If invert == True, sort
- *against* that convention.
+ Compare a general attribute between two bugs using the
+ conventional comparison rule for that attribute type. If
+ ``invert==True``, sort *against* that convention.
+
>>> attr="severity"
>>> bugA = Bug()
>>> bugB = Bug()
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-"""
-Define the BugDir class for representing bug comments.
+"""Define the :class:`BugDir` class for storing a collection of bugs.
"""
import copy
class BugDir (list, settings_object.SavedSettingsObject):
- """
- TODO: simple bugdir manipulation examples...
+ """A BugDir is a container for :class:`libbe.bug.Bug`\s, with some
+ additional attributes.
+
+ See :class:`SimpleBugDir` for some bugdir manipulation exampes.
"""
settings_properties = []
if libbe.TESTING == True:
class SimpleBugDir (BugDir):
"""
- For testing. Set memory=True for a memory-only bugdir.
+ For testing. Set ``memory=True`` for a memory-only bugdir.
+
>>> bugdir = SimpleBugDir()
>>> uuids = list(bugdir.uuids())
>>> uuids.sort()
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-"""
-Define the Comment class for representing bug comments.
+"""Define the :class:`Comment` class for representing bug comments.
"""
import base64
class Comment (Tree, settings_object.SavedSettingsObject):
- """
+ """Comments are a notes that attach to :class:`libbe.bug.Bug`\s in
+ threaded trees. In mailing-list terms, a comment is analogous to
+ a single part of an email.
+
>>> c = Comment()
>>> c.uuid != None
True
def __init__(self, bug=None, uuid=None, from_storage=False,
in_reply_to=None, body=None, content_type=None):
"""
- Set from_storage=True to load an old comment.
- Set from_storage=False to create a new comment.
+ Set ``from_storage=True`` to load an old comment.
+ Set ``from_storage=False`` to create a new comment.
- The uuid option is required when from_storage==True.
+ The ``uuid`` option is required when ``from_storage==True``.
The in_reply_to, body, and content_type options are only used
- if from_storage==False (the default). When
- from_storage==True, they are loaded from the bug database.
- content_type decides if the body should be run through
- libbe.util.id.short_to_long_text() before saving. See
- ._set_comment_body() for details.
+ if ``from_storage==False`` (the default). When
+ ``from_storage==True``, they are loaded from the bug database.
+ ``content_type`` decides if the body should be run through
+ :func:`util.id.short_to_long_text` before saving. See
+ :meth:`_set_comment_body` for details.
- in_reply_to should be the uuid string of the parent comment.
+ ``in_reply_to`` should be the uuid string of the parent comment.
"""
Tree.__init__(self)
settings_object.SavedSettingsObject.__init__(self)
def safe_in_reply_to(self):
"""
Return self.in_reply_to, except...
+
* if no comment matches that id, in which case return None.
* if that id matches another comments .alt_id, in which case
return the matching comments .uuid.
return istring + sep.join(lines).rstrip('\n')
def from_xml(self, xml_string, verbose=True):
- """
+ u"""
Note: If alt-id is not given, translates any <uuid> fields to
<alt-id> fields.
>>> commA = Comment(bug=None, body="Some\\ninsightful\\nremarks\\n")
"""
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'
"""
Save any loaded contents to storage.
- However, if self.storage.is_writeable() == True, then any
+ 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).
return reply
def comment_from_uuid(self, uuid, match_alt_id=True):
- """
- Use a uuid to look up a comment.
+ """Use a uuid to look up a comment.
+
>>> a = Comment(bug=None, uuid="a")
>>> b = a.new_reply()
>>> b.uuid = "b"
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()
projects / be.git / commitdiff