------------------------------------------------------------
revno: 6541
committer: Barry Warsaw <[EMAIL PROTECTED]>
branch nick: 3.0
timestamp: Sun 2007-08-05 07:30:30 -0400
message:
Added a doctest for styles.
added:
Mailman/docs/styles.txt
modified:
Mailman/app/styles.py
=== added file 'Mailman/docs/styles.txt'
--- a/Mailman/docs/styles.txt 1970-01-01 00:00:00 +0000
+++ b/Mailman/docs/styles.txt 2007-08-05 11:30:30 +0000
@@ -0,0 +1,142 @@
+List styles
+===========
+
+List styles are a way to name and apply a canned collection of attribute
+settings. Every style has a name, which must be unique within the context of
+a specific style manager. There is usually only one global style manager.
+
+Styles also have a priority, which allows you to specify the order in which
+multiple styles will be applied. A style has a `match` function which is used
+to determine whether the style should be applied to a particular mailing list
+or not. And finally, application of a style to a mailing list can really
+modify the mailing list any way it wants.
+
+Let's start with a vanilla mailing list and a default style manager.
+
+ >>> from Mailman.configuration import config
+ >>> from Mailman.database import flush
+ >>> mlist = config.db.list_manager.create('[EMAIL PROTECTED]')
+ >>> from Mailman.app.styles import style_manager
+
+
+The default style
+-----------------
+
+There is a default style which implements the legacy application of list
+defaults from Defaults.py. This style only matching a mailing list when no
+other styles match, and it has the lowest priority. The low priority means
+that it is matched last and if it matches, it is applied last.
+
+ >>> default_style = style_manager.get('default')
+ >>> default_style.name
+ 'default'
+ >>> default_style.priority
+ 0
+ >>> sorted(style.name for style in style_manager.styles)
+ ['default']
+
+Given a mailing list, you can ask the style manager to find all the styles
+that match the list. The registered styles will be sorted by decreasing
+priority and each style's `match()` method will be called in turn. The sorted
+list of matching styles will be returned -- but not applied -- by the style
+manager's `lookup()` method.
+
+ >>> [style.name for style in style_manager.lookup(mlist)]
+ ['default']
+
+If the site administrator modified their mailman.cfg file, the default style
+would pick this up and apply it to the mailing list.
+
+ >>> print mlist.msg_footer
+ None
+ >>> config.DEFAULT_MSG_FOOTER = u'default footer'
+ >>> default_style.apply(mlist)
+ >>> flush()
+ >>> mlist.msg_footer
+ u'default footer'
+
+
+Registering styles
+------------------
+
+New styles must implement the IStyle interface.
+
+ >>> from zope.interface import implements
+ >>> from Mailman.interfaces import IStyle
+ >>> class TestStyle(object):
+ ... name = 'test'
+ ... priority = 10
+ ... def apply(self, mailing_list):
+ ... # Just does something very simple.
+ ... mailing_list.msg_footer = u'test footer'
+ ... def match(self, mailing_list, styles):
+ ... # Applies to any test list
+ ... if 'test' in mailing_list.fqdn_listname:
+ ... styles.append(self)
+
+You can register a new style with the style manager.
+
+ >>> style_manager.register(TestStyle())
+
+And now if you lookup matching styles, you should find only the new test
+style. This is because the default style only gets applied when no other
+styles match the mailing list.
+
+ >>> sorted(style.name for style in style_manager.lookup(mlist))
+ ['test']
+ >>> for style in style_manager.lookup(mlist):
+ ... style.apply(mlist)
+ >>> flush()
+ >>> mlist.msg_footer
+ u'test footer'
+
+
+Style priority
+--------------
+
+When multiple styles match a particular mailing list, they are applied in
+descending order of priority. In other words, a priority zero style would be
+applied last.
+
+ >>> class AnotherTestStyle(TestStyle):
+ ... name = 'another'
+ ... priority = 5
+ ... # Use the base class's match() method.
+ ... def apply(self, mailing_list):
+ ... mailing_list.msg_footer = u'another footer'
+
+ >>> mlist.msg_footer = u''
+ >>> flush()
+ >>> mlist.msg_footer
+ u''
+ >>> style_manager.register(AnotherTestStyle())
+ >>> for style in style_manager.lookup(mlist):
+ ... style.apply(mlist)
+ >>> flush()
+ >>> mlist.msg_footer
+ u'another footer'
+
+You can change the priority of a style, and if you reapply the styles, they
+will take effect in the new priority order.
+
+ >>> style_1 = style_manager.get('test')
+ >>> style_1.priority = 5
+ >>> style_2 = style_manager.get('another')
+ >>> style_2.priority = 10
+ >>> for style in style_manager.lookup(mlist):
+ ... style.apply(mlist)
+ >>> flush()
+ >>> mlist.msg_footer
+ u'test footer'
+
+
+Corner cases
+------------
+
+If you register a style with the same name as an already registered style, you
+get an exception.
+
+ >>> style_manager.register(AnotherTestStyle())
+ Traceback (most recent call last):
+ ...
+ DuplicateStyleError: another
=== modified file 'Mailman/app/styles.py'
--- a/Mailman/app/styles.py 2007-08-05 04:32:09 +0000
+++ b/Mailman/app/styles.py 2007-08-05 11:30:30 +0000
@@ -45,6 +45,8 @@
priority = 0 # the lowest priority style
def apply(self, mailing_list):
+ # For cut-n-paste convenience.
+ mlist = mailing_list
# Most of these were ripped from the old MailList.InitVars() method.
mlist.volume = 1
mlist.post_id = 1
@@ -248,12 +250,14 @@
matched_styles = []
for style in self.styles:
style.match(mailing_list, matched_styles)
- for style in sorted(matched_styles, key=attrgetter('priority')):
+ for style in matched_styles:
yield style
@property
def styles(self):
- for style in sorted(self._styles.values(), key=attrgetter('priority')):
+ for style in sorted(self._styles.values(),
+ key=attrgetter('priority'),
+ reverse=True):
yield style
def register(self, style):
--
(no title)
https://code.launchpad.net/~mailman-coders/mailman/3.0
You are receiving this branch notification because you are subscribed to it.
To unsubscribe from this branch go to
https://code.launchpad.net/~mailman-coders/mailman/3.0/+subscription/mailman-checkins.
_______________________________________________
Mailman-checkins mailing list
[email protected]
Unsubscribe:
http://mail.python.org/mailman/options/mailman-checkins/archive%40jab.org
