def __init__(self,
watch_mode,
interesting_steps,
boring_steps=None,
**kwargs):
"""
@type watch_mode: either BUILDERS or CATEGORIES
@param watch_mode: A singleton object denoting whether this class is
watching steps keyed by builder name or by category.
@type interesting_steps: mapping of strings to lists of strings.
@param interesting_steps: Keys are either builder names or categories;
values are lists of steps which we care about.
The key '*' (wildcard) means 'all builders'.
The value ['*'] (wildcard) means 'all steps'.
All keys (other than wildcard) must be present in
either |builders| or |categories| (in kwargs).
Required since otherwise this class has no point.
@type boring_steps: mapping of strings to lists of strings.
@param boring_steps: Keys are either builder names or categories;
values are lists of steps which we do not care about.
The key '*' (wildcard) means 'all builders'.
The value ['*'] (wildcard) means 'all steps'.
All keys (other than wildcard) must be present in
either |builders| or |categories| (in kwargs).
Boring steps override interesting steps.
"""
self.watch_mode = watch_mode
self.interesting_steps = interesting_steps
self.boring_steps = boring_steps or {}
# Pass through the keys in interesting/boring steps to the appropriate list
# in the parent class.
if any((arg in ('builders', 'categores') for arg in kwargs)):
raise interfaces.ParameterError(
'Please do not specify |builders| or |categories| in StepNotifier.'
)
keys = set(self.interesting_steps) | set(self.boring_steps)
keys.discard('*')
if self.watch_mode is BUILDERS:
kwargs['builders'] = list(keys)
elif self.watch_mode is CATEGORIES:
kwargs['categories'] = list(keys)
else:
raise interfaces.ParameterError(
'Please specify either BUILDERS or CATEGORIES for |watch_mode|.'
)
self.log('Interesting steps: %s' % self.interesting_steps)
self.log('Boring steps: %s' % self.boring_steps)
self.log('Instantiating MailNotifier with: %s' % kwargs)
# Don't use super because MailNotifier is an old-style class.
MailNotifier.__init__(self, **kwargs)
def __init__(
self,
fromaddr,
mode="all",
categories=None,
builders=None,
addLogs=False,
relayhost="localhost",
subject="buildbot %(result)s in %(projectName)s on %(builder)s",
lookup=None,
extraRecipients=[],
sendToInterestedUsers=True,
customMesg=None,
messageFormatter=defaultMessage,
extraHeaders=None,
addPatch=True,
useTls=False,
smtpUser=None,
smtpPassword=None,
smtpPort=25):
"""
@type fromaddr: string
@param fromaddr: the email address to be used in the 'From' header.
@type sendToInterestedUsers: boolean
@param sendToInterestedUsers: if True (the default), send mail to all
of the Interested Users. If False, only
send mail to the extraRecipients list.
@type extraRecipients: tuple of string
@param extraRecipients: a list of email addresses to which messages
should be sent (in addition to the
InterestedUsers list, which includes any
developers who made Changes that went into this
build). It is a good idea to create a small
mailing list and deliver to that, then let
subscribers come and go as they please. The
addresses in this list are used literally (they
are not processed by lookup).
@type subject: string
@param subject: a string to be used as the subject line of the message.
%(builder)s will be replaced with the name of the
builder which provoked the message.
@type mode: string (defaults to all)
@param mode: one of:
- 'all': send mail about all builds, passing and failing
- 'failing': only send mail about builds which fail
- 'warnings': send mail if builds contain warnings or fail
- 'passing': only send mail about builds which succeed
- 'problem': only send mail about a build which failed
when the previous build passed
- 'change': only send mail about builds who change status
@type builders: list of strings
@param builders: a list of builder names for which mail should be
sent. Defaults to None (send mail for all builds).
Use either builders or categories, but not both.
@type categories: list of strings
@param categories: a list of category names to serve status
information for. Defaults to None (all
categories). Use either builders or categories,
but not both.
@type addLogs: boolean
@param addLogs: if True, include all build logs as attachments to the
messages. These can be quite large. This can also be
set to a list of log names, to send a subset of the
logs. Defaults to False.
@type addPatch: boolean
@param addPatch: if True, include the patch when the source stamp
includes one.
@type relayhost: string
@param relayhost: the host to which the outbound SMTP connection
should be made. Defaults to 'localhost'
@type lookup: implementor of {IEmailLookup}
@param lookup: object which provides IEmailLookup, which is
responsible for mapping User names for Interested
Users (which come from the VC system) into valid
email addresses. If not provided, the notifier will
only be able to send mail to the addresses in the
extraRecipients list. Most of the time you can use a
simple Domain instance. As a shortcut, you can pass
as string: this will be treated as if you had provided
Domain(str). For example, lookup='twistedmatrix.com'
will allow mail to be sent to all developers whose SVN
usernames match their twistedmatrix.com account names.
@type customMesg: func
@param customMesg: (this function is deprecated)
@type messageFormatter: func
@param messageFormatter: function taking (mode, name, build, result,
master_status) and returning a dictionary
containing two required keys "body" and "type",
with a third optional key, "subject". The
"body" key gives a string that contains the
complete text of the message. The "type" key
is the message type ('plain' or 'html'). The
'html' type should be used when generating an
HTML message. The optional "subject" key
gives the subject for the email.
@type extraHeaders: dict
@param extraHeaders: A dict of extra headers to add to the mail. It's
best to avoid putting 'To', 'From', 'Date',
'Subject', or 'CC' in here. Both the names and
values may be WithProperties instances.
@type useTls: boolean
@param useTls: Send emails using TLS and authenticate with the
smtp host. Defaults to False.
@type smtpUser: string
@param smtpUser: The user that will attempt to authenticate with the
relayhost when useTls is True.
@type smtpPassword: string
@param smtpPassword: The password that smtpUser will use when
authenticating with relayhost.
@type smtpPort: int
@param smtpPort: The port that will be used when connecting to the
relayhost. Defaults to 25.
"""
base.StatusReceiverMultiService.__init__(self)
assert isinstance(extraRecipients, (list, tuple))
for r in extraRecipients:
assert isinstance(r, str)
# require full email addresses, not User names
assert VALID_EMAIL.search(r), "%s is not a valid email" % r
self.extraRecipients = extraRecipients
self.sendToInterestedUsers = sendToInterestedUsers
self.fromaddr = fromaddr
assert mode in ('all', 'failing', 'problem', 'change', 'passing',
'warnings')
self.mode = mode
self.categories = categories
self.builders = builders
self.addLogs = addLogs
self.relayhost = relayhost
self.subject = subject
if lookup is not None:
if type(lookup) is str:
lookup = Domain(lookup)
assert interfaces.IEmailLookup.providedBy(lookup)
self.lookup = lookup
self.customMesg = customMesg
self.messageFormatter = messageFormatter
if extraHeaders:
assert isinstance(extraHeaders, dict)
self.extraHeaders = extraHeaders
self.addPatch = addPatch
self.useTls = useTls
self.smtpUser = smtpUser
self.smtpPassword = smtpPassword
self.smtpPort = smtpPort
self.watched = []
self.master_status = None
# you should either limit on builders or categories, not both
if self.builders != None and self.categories != None:
twlog.err(
"Please specify only builders or categories to include not both."
)
raise interfaces.ParameterError(
"Please specify only builders or categories to include not both."
)
if customMesg:
twlog.msg(
"customMesg is deprecated; please use messageFormatter instead"
)
