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" )