- issue1714899: Feature Request: Optional Change Note. Added a new

  quiet=True/False option for all property types. When quiet=True
  changes to the property will not be displayed in the::

    confirmation banner (shown in green) when a change is made
    property change section of change note (nosy emails)
    web history display for an item.

  Note that this may confuse users if used on a property that is
  meant to be changed by a user. It is most useful on administrative
  properties that are changed by an auditor as part of a user
  generated change. Original patch by Daniel Diniz (ajaksu2)
  discussed also at:
    http://psf.upfronthosting.co.za/roundup/meta/issue249
  Support for setting quiet when calling the class specifiers:
  E.G. prop=String(quiet=True) rather than::
    prop=String()
    prop.quiet=True
  support for anydb backend, added tests, doc updates, support for
  ignoring quiet setting using showall=True in call to history()
  function in templates by John Rouillard.

In addition to documenting quiet, I also documented required and
default_value additions to the hyperdb property classes. Only place I
could find is design.txt.

Note tests for history in web interface are not done. It was manually
checked but there are no automated tests. The template for setup is in
db_test_base.py::testQuietJournal but it has no asserts.  I need
access to template.py::_HTMLItem::history() and I don't know how to do
that. test_templates.py isn't helping me any at all and I want to get
this patch in because it handles nicely an issue I have in the design
of my own tracker. The issue is:

  The properties of an issue are displayed in framesets/subframes. The
  user can roll up the frameset leaving only the title bar. When the
  user saves the changes, the current state of the framesets
  (collapsed/uncollapsed) is saved to a property in the user's
  object. However there is no reason the user should see that this is
  updated since it's an administrative detail.

Similarly, you could count the number of times an issue is reopened or
reassigned. Updates to properties that are an indirect result of a
user's change should not be displayed to the user as they can be
confusing and distracting.

Author: rouilj

CHANGES.txt

@@ -87,6 +87,25 @@ Features:
     3) setting it to a fixed address (like [email protected])
   Done by John Rouillard from proposal by Peter Funk (pefu)
   in discussion with Tom Ekberg (tekberg). See doc/upgrading.txt.
+- issue1714899: Feature Request: Optional Change Note. Added a new
+  quiet=True/False option for all property types. When quiet=True
+  changes to the property will not be displayed in the::
+    confirmation banner (shown in green) when a change is made
+    property change section of change note (nosy emails)
+    web history display for an item.
+  Note that this may confuse users if used on a property that is
+  meant to be changed by a user. It is most useful on administrative
+  properties that are changed by an auditor as part of a user
+  generated change. Original patch by Daniel Diniz (ajaksu2)
+  discussed also at:
+    http://psf.upfronthosting.co.za/roundup/meta/issue249
+  Support for setting quiet when calling the class specifiers:
+  E.G. prop=String(quiet=True) rather than::
+    prop=String()
+    prop.quiet=True
+  support for anydb backend, added tests, doc updates, support for
+  ignoring quiet setting using showall=True in call to history()
+  function in templates by John Rouillard.
 
 Fixed:
 

doc/design.txt

@@ -254,8 +254,44 @@ Hyperdb Interface Specification
 TODO: replace the Interface Specifications with links to the pydoc
 
 The hyperdb module provides property objects to designate the different
-kinds of properties.  These objects are used when specifying what
-properties belong in classes::
+kinds of properties.
+
+All property objects support the following settings:
+
+quiet=False:
+      if set to True, changes to the property will not be shown to the
+      user. This can be used for adminstrative properties that are
+      automatically updated when a user makes some other change. This
+      reduces confusion by the user and clutter in the display.
+      The property change will not be shown in:
+
+        - the change confirmation message when a change is entered in the web interface
+        - the property change section of the change note email ("nosy email")
+        - the web history shown at the bottom of an item page
+
+required=False:
+        if set to True, the property name is returned when calling
+        get_required_props(self, propnames = []). Any additional props
+        specified in propnames is merged with the required props.
+
+default_value=None or [] depending on object type:
+        this sets the default value if none is specified. The default
+        value can be retrieved by calling the get_default_value()
+        method on the property object.
+ 
+E.G. assuming title is part of an Issue::
+
+    title=String(required=True, default_value="not set",quiet=True)
+
+will create a property called ``title`` that will be included in the
+get_required_props() output. Calling
+db.issue.properties['title'].get_default_value() will return "not set".
+Changes to the property will not be displayed in emailed change notes,
+the history at the end of the item pages in the web interface and will
+be suppressed in the confirmation notice (displayed as a green banner)
+shown on changes.
+
+These objects are used when specifying what properties belong in classes::
 
     class String:
         def __init__(self, indexme='no'):
@@ -1652,6 +1688,7 @@ and Dean Tribble for their assistance with the first-round submission.
 Changes to this document
 ------------------------
 
+- Added docs for quiet, default_value and required arguments for properties.
 - Added Boolean, Integer and Number types
 - Added section Hyperdatabase Implementations
 - "Item" has been renamed to "Issue" to account for the more specific

roundup/backends/back_anydbm.py

@@ -1199,6 +1199,9 @@ def set_inner(self, nodeid, **propvalues):
         # if the journal value is to be different, store it in here
         journalvalues = {}
 
+        # omit quiet properties from history/changelog
+        quiet_props = []
+
         # list() propvalues 'cos it might be modified by the loop
         for propname, value in list(propvalues.items()):
             # check to make sure we're not duplicating an existing key
@@ -1374,6 +1377,10 @@ def set_inner(self, nodeid, **propvalues):
 
             node[propname] = value
 
+            # record quiet properties to omit from history/changelog
+            if prop.quiet:
+                quiet_props.append(propname)
+
         # nothing to do?
         if not propvalues:
             return propvalues
@@ -1388,6 +1395,11 @@ def set_inner(self, nodeid, **propvalues):
         if self.do_journal:
             self.db.addjournal(self.classname, nodeid, 'set', journalvalues)
 
+        # remove quiet properties from output
+        for propname in quiet_props:
+            if propname in propvalues:
+                del propvalues[propname]
+
         return propvalues
 
     def retire(self, nodeid):

roundup/backends/rdbms_common.py

@@ -1783,6 +1783,9 @@ def set_inner(self, nodeid, **propvalues):
         # for the Database layer to do its stuff
         multilink_changes = {}
 
+        # omit quiet properties from history/changelog
+        quiet_props = []
+
         for propname, value in list(propvalues.items()):
             # check to make sure we're not duplicating an existing key
             if propname == self.key and node[propname] != value:
@@ -1958,6 +1961,10 @@ def set_inner(self, nodeid, **propvalues):
                 except ValueError:
                     raise TypeError('new property "%s" not boolean'%propname)
 
+            # record quiet properties to omit from history/changelog
+            if prop.quiet:
+                quiet_props.append(propname)
+
         # nothing to do?
         if not propvalues:
             return propvalues
@@ -1977,6 +1984,11 @@ def set_inner(self, nodeid, **propvalues):
         if self.do_journal:
             self.db.addjournal(self.classname, nodeid, ''"set", journalvalues)
 
+        # remove quiet properties from output
+        for propname in quiet_props:
+            if propname in propvalues:
+                del propvalues[propname]
+
         return propvalues
 
     def retire(self, nodeid):

roundup/cgi/templating.py

@@ -870,7 +870,13 @@ def journal(self, direction='descending'):
         return []
 
     def history(self, direction='descending', dre=re.compile('^\d+$'),
-            limit=None):
+                limit=None, showall=False ):
+        """Create an html view of the journal for the item.
+
+           Display property changes for all properties that does not have quiet set.
+           If showall=True then all properties regardless of quiet setting will be
+           shown.
+        """
         if not self.is_view_ok():
             return self._('[hidden]')
 
@@ -965,7 +971,10 @@ def history(self, direction='descending', dre=re.compile('^\d+$'),
                         except NoTemplate:
                             hrefable = 0
 
-                    if isinstance(prop, hyperdb.Multilink) and args[k]:
+                    if (not showall) and prop.quiet:
+                        # Omit quiet properties from history/changelog
+                        continue
+                    elif isinstance(prop, hyperdb.Multilink) and args[k]:
                         ml = []
                         for linkid in args[k]:
                             if isinstance(linkid, type(())):

roundup/hyperdb.py

@@ -35,9 +35,10 @@
 #
 class _Type(object):
     """A roundup property type."""
-    def __init__(self, required=False, default_value = None):
+    def __init__(self, required=False, default_value = None, quiet=False):
         self.required = required
         self.__default_value = default_value
+        self.quiet = quiet
     def __repr__(self):
         ' more useful for dumps '
         return '<%s.%s>'%(self.__class__.__module__, self.__class__.__name__)
@@ -54,8 +55,8 @@ def sort_repr (self, cls, val, name):
 
 class String(_Type):
     """An object designating a String property."""
-    def __init__(self, indexme='no', required=False, default_value = ""):
-        super(String, self).__init__(required, default_value)
+    def __init__(self, indexme='no', required=False, default_value = "", quiet=False):
+        super(String, self).__init__(required, default_value, quiet)
         self.indexme = indexme == 'yes'
     def from_raw(self, value, propname='', **kw):
         """fix the CRLF/CR -> LF stuff"""
@@ -73,8 +74,8 @@ def sort_repr (self, cls, val, name):
 
 class Password(_Type):
     """An object designating a Password property."""
-    def __init__(self, scheme=None, required=False, default_value = None):
-        super(Password, self).__init__(required, default_value)
+    def __init__(self, scheme=None, required=False, default_value = None, quiet=False):
+        super(Password, self).__init__(required, default_value, quiet)
         self.scheme = scheme
 
     def from_raw(self, value, **kw):
@@ -93,9 +94,10 @@ def sort_repr (self, cls, val, name):
 
 class Date(_Type):
     """An object designating a Date property."""
-    def __init__(self, offset=None, required=False, default_value = None):
+    def __init__(self, offset=None, required=False, default_value = None, quiet=False):
         super(Date, self).__init__(required = required,
-                                   default_value = default_value)
+                                   default_value = default_value,
+                                   quiet=quiet)
         self._offset = offset
     def offset(self, db):
         if self._offset is not None:
@@ -135,7 +137,7 @@ class _Pointer(_Type):
     to a node in a specified class."""
     def __init__(self, classname, do_journal='yes', try_id_parsing='yes',
                  required=False, default_value=None,
-                 msg_header_property = None):
+                 msg_header_property = None, quiet=False):
         """ Default is to journal link and unlink events.
             When try_id_parsing is false, we don't allow IDs in input
             fields (the key of the Link or Multilink property must be
@@ -154,7 +156,7 @@ def __init__(self, classname, do_journal='yes', try_id_parsing='yes',
             property will generated message headers of the form:
             'X-Roundup-issue-assigned_to: joe_user'.
         """
-        super(_Pointer, self).__init__(required, default_value)
+        super(_Pointer, self).__init__(required, default_value, quiet)
         self.classname = classname
         self.do_journal = do_journal == 'yes'
         self.try_id_parsing      = try_id_parsing == 'yes'
@@ -196,12 +198,12 @@ class Multilink(_Pointer):
                     'link' and 'unlink' events placed in their journal
     """
 
-    def __init__(self, classname, do_journal = 'yes', required = False):
+    def __init__(self, classname, do_journal = 'yes', required = False, quiet=False):
 
         super(Multilink, self).__init__(classname,
                                         do_journal,
                                         required = required,
-                                        default_value = [])        
+                                        default_value = [], quiet=quiet)
 
     def from_raw(self, value, db, klass, propname, itemid, **kw):
         if not value:

roundup/roundupdb.py

@@ -703,6 +703,9 @@ def generateCreateNote(self, issueid):
         prop_items = props.items()
         prop_items.sort()
         for propname, prop in prop_items:
+            # Omit quiet properties from history/changelog
+            if prop.quiet:
+                continue
             value = cl.get(issueid, propname, None)
             # skip boring entries
             if not value:
@@ -775,6 +778,9 @@ def generateChangeNote(self, issueid, oldvalues):
         changed_items.sort()
         for propname, oldvalue in changed_items:
             prop = props[propname]
+            # Omit quiet properties from history/changelog
+            if prop.quiet:
+                continue
             value = cl.get(issueid, propname, None)
             if isinstance(prop, hyperdb.Link):
                 link = self.db.classes[prop.classname]