Code

Fix small typos.
[roundup.git] / roundup / configuration.py
1 # Roundup Issue Tracker configuration support
2 #
3 # $Id: configuration.py,v 1.51 2008-09-01 02:30:06 richard Exp $
4 #
5 __docformat__ = "restructuredtext"
7 import ConfigParser
8 import getopt
9 import imp
10 import logging, logging.config
11 import os
12 import re
13 import sys
14 import time
15 import smtplib
17 import roundup.date
19 # XXX i don't think this module needs string translation, does it?
21 ### Exceptions
23 class ConfigurationError(Exception):
24     pass
26 class NoConfigError(ConfigurationError):
28     """Raised when configuration loading fails
30     Constructor parameters: path to the directory that was used as HOME
32     """
34     def __str__(self):
35         return "No valid configuration files found in directory %s" \
36             % self.args[0]
38 class InvalidOptionError(ConfigurationError, KeyError, AttributeError):
40     """Attempted access to non-existing configuration option
42     Configuration options may be accessed as configuration object
43     attributes or items.  So this exception instances also are
44     instances of KeyError (invalid item access) and AttributeError
45     (invalid attribute access).
47     Constructor parameter: option name
49     """
51     def __str__(self):
52         return "Unsupported configuration option: %s" % self.args[0]
54 class OptionValueError(ConfigurationError, ValueError):
56     """Raised upon attempt to assign an invalid value to config option
58     Constructor parameters: Option instance, offending value
59     and optional info string.
61     """
63     def __str__(self):
64         _args = self.args
65         _rv = "Invalid value for %(option)s: %(value)r" % {
66             "option": _args[0].name, "value": _args[1]}
67         if len(_args) > 2:
68             _rv += "\n".join(("",) + _args[2:])
69         return _rv
71 class OptionUnsetError(ConfigurationError):
73     """Raised when no Option value is available - neither set, nor default
75     Constructor parameters: Option instance.
77     """
79     def __str__(self):
80         return "%s is not set and has no default" % self.args[0].name
82 class UnsetDefaultValue:
84     """Special object meaning that default value for Option is not specified"""
86     def __str__(self):
87         return "NO DEFAULT"
89 NODEFAULT = UnsetDefaultValue()
91 ### Option classes
93 class Option:
95     """Single configuration option.
97     Options have following attributes:
99         config
100             reference to the containing Config object
101         section
102             name of the section in the tracker .ini file
103         setting
104             option name in the tracker .ini file
105         default
106             default option value
107         description
108             option description.  Makes a comment in the tracker .ini file
109         name
110             "canonical name" of the configuration option.
111             For items in the 'main' section this is uppercased
112             'setting' name.  For other sections, the name is
113             composed of the section name and the setting name,
114             joined with underscore.
115         aliases
116             list of "also known as" names.  Used to access the settings
117             by old names used in previous Roundup versions.
118             "Canonical name" is also included.
120     The name and aliases are forced to be uppercase.
121     The setting name is forced to lowercase.
123     """
125     class_description = None
127     def __init__(self, config, section, setting,
128         default=NODEFAULT, description=None, aliases=None
129     ):
130         self.config = config
131         self.section = section
132         self.setting = setting.lower()
133         self.default = default
134         self.description = description
135         self.name = setting.upper()
136         if section != "main":
137             self.name = "_".join((section.upper(), self.name))
138         if aliases:
139             self.aliases = [alias.upper() for alias in list(aliases)]
140         else:
141             self.aliases = []
142         self.aliases.insert(0, self.name)
143         # convert default to internal representation
144         if default is NODEFAULT:
145             _value = default
146         else:
147             _value = self.str2value(default)
148         # value is private.  use get() and set() to access
149         self._value = self._default_value = _value
151     def str2value(self, value):
152         """Return 'value' argument converted to internal representation"""
153         return value
155     def _value2str(self, value):
156         """Return 'value' argument converted to external representation
158         This is actual conversion method called only when value
159         is not NODEFAULT.  Heirs with different conversion rules
160         override this method, not the public .value2str().
162         """
163         return str(value)
165     def value2str(self, value=NODEFAULT, current=0):
166         """Return 'value' argument converted to external representation
168         If 'current' is True, use current option value.
170         """
171         if current:
172             value = self._value
173         if value is NODEFAULT:
174             return str(value)
175         else:
176             return self._value2str(value)
178     def get(self):
179         """Return current option value"""
180         if self._value is NODEFAULT:
181             raise OptionUnsetError(self)
182         return self._value
184     def set(self, value):
185         """Update the value"""
186         self._value = self.str2value(value)
188     def reset(self):
189         """Reset the value to default"""
190         self._value = self._default_value
192     def isdefault(self):
193         """Return True if current value is the default one"""
194         return self._value == self._default_value
196     def isset(self):
197         """Return True if the value is available (either set or default)"""
198         return self._value != NODEFAULT
200     def __str__(self):
201         return self.value2str(self._value)
203     def __repr__(self):
204         if self.isdefault():
205             _format = "<%(class)s %(name)s (default): %(value)s>"
206         else:
207             _format = "<%(class)s %(name)s (default: %(default)s): %(value)s>"
208         return _format % {
209             "class": self.__class__.__name__,
210             "name": self.name,
211             "default": self.value2str(self._default_value),
212             "value": self.value2str(self._value),
213         }
215     def format(self):
216         """Return .ini file fragment for this option"""
217         _desc_lines = []
218         for _description in (self.description, self.class_description):
219             if _description:
220                 _desc_lines.extend(_description.split("\n"))
221         # comment out the setting line if there is no value
222         if self.isset():
223             _is_set = ""
224         else:
225             _is_set = "#"
226         _rv = "# %(description)s\n# Default: %(default)s\n" \
227             "%(is_set)s%(name)s = %(value)s\n" % {
228                 "description": "\n# ".join(_desc_lines),
229                 "default": self.value2str(self._default_value),
230                 "name": self.setting,
231                 "value": self.value2str(self._value),
232                 "is_set": _is_set
233             }
234         return _rv
236     def load_ini(self, config):
237         """Load value from ConfigParser object"""
238         if config.has_option(self.section, self.setting):
239             self.set(config.get(self.section, self.setting))
241     def load_pyconfig(self, config):
242         """Load value from old-style config (python module)"""
243         for _name in self.aliases:
244             if hasattr(config, _name):
245                 self.set(getattr(config, _name))
246                 break
248 class BooleanOption(Option):
250     """Boolean option: yes or no"""
252     class_description = "Allowed values: yes, no"
254     def _value2str(self, value):
255         if value:
256             return "yes"
257         else:
258             return "no"
260     def str2value(self, value):
261         if type(value) == type(""):
262             _val = value.lower()
263             if _val in ("yes", "true", "on", "1"):
264                 _val = 1
265             elif _val in ("no", "false", "off", "0"):
266                 _val = 0
267             else:
268                 raise OptionValueError(self, value, self.class_description)
269         else:
270             _val = value and 1 or 0
271         return _val
273 class WordListOption(Option):
275     """List of strings"""
277     class_description = "Allowed values: comma-separated list of words"
279     def _value2str(self, value):
280         return ','.join(value)
282     def str2value(self, value):
283         return value.split(',')
285 class RunDetectorOption(Option):
287     """When a detector is run: always, never or for new items only"""
289     class_description = "Allowed values: yes, no, new"
291     def str2value(self, value):
292         _val = value.lower()
293         if _val in ("yes", "no", "new"):
294             return _val
295         else:
296             raise OptionValueError(self, value, self.class_description)
298 class MailAddressOption(Option):
300     """Email address
302     Email addresses may be either fully qualified or local.
303     In the latter case MAIL_DOMAIN is automatically added.
305     """
307     def get(self):
308         _val = Option.get(self)
309         if "@" not in _val:
310             _val = "@".join((_val, self.config["MAIL_DOMAIN"]))
311         return _val
313 class FilePathOption(Option):
315     """File or directory path name
317     Paths may be either absolute or relative to the HOME.
319     """
321     class_description = "The path may be either absolute or relative\n" \
322         "to the directory containig this config file."
324     def get(self):
325         _val = Option.get(self)
326         if _val and not os.path.isabs(_val):
327             _val = os.path.join(self.config["HOME"], _val)
328         return _val
330 class FloatNumberOption(Option):
332     """Floating point numbers"""
334     def str2value(self, value):
335         try:
336             return float(value)
337         except ValueError:
338             raise OptionValueError(self, value,
339                 "Floating point number required")
341     def _value2str(self, value):
342         _val = str(value)
343         # strip fraction part from integer numbers
344         if _val.endswith(".0"):
345             _val = _val[:-2]
346         return _val
348 class IntegerNumberOption(Option):
350     """Integer numbers"""
352     def str2value(self, value):
353         try:
354             return int(value)
355         except ValueError:
356             raise OptionValueError(self, value, "Integer number required")
358 class OctalNumberOption(Option):
360     """Octal Integer numbers"""
362     def str2value(self, value):
363         try:
364             return int(value, 8)
365         except ValueError:
366             raise OptionValueError(self, value, "Octal Integer number required")
368     def _value2str(self, value):
369         return oct(value)
371 class NullableOption(Option):
373     """Option that is set to None if its string value is one of NULL strings
375     Default nullable strings list contains empty string only.
376     There is constructor parameter allowing to specify different nullables.
378     Conversion to external representation returns the first of the NULL
379     strings list when the value is None.
381     """
383     NULL_STRINGS = ("",)
385     def __init__(self, config, section, setting,
386         default=NODEFAULT, description=None, aliases=None,
387         null_strings=NULL_STRINGS
388     ):
389         self.null_strings = list(null_strings)
390         Option.__init__(self, config, section, setting, default,
391             description, aliases)
393     def str2value(self, value):
394         if value in self.null_strings:
395             return None
396         else:
397             return value
399     def _value2str(self, value):
400         if value is None:
401             return self.null_strings[0]
402         else:
403             return value
405 class NullableFilePathOption(NullableOption, FilePathOption):
407     # .get() and class_description are from FilePathOption,
408     get = FilePathOption.get
409     class_description = FilePathOption.class_description
410     # everything else taken from NullableOption (inheritance order)
412 class TimezoneOption(Option):
414     class_description = \
415         "If pytz module is installed, value may be any valid\n" \
416         "timezone specification (e.g. EET or Europe/Warsaw).\n" \
417         "If pytz is not installed, value must be integer number\n" \
418         "giving local timezone offset from UTC in hours."
420     def str2value(self, value):
421         try:
422             roundup.date.get_timezone(value)
423         except KeyError:
424             raise OptionValueError(self, value,
425                     "Timezone name or numeric hour offset required")
426         return value
428 class RegExpOption(Option):
430     """Regular Expression option (value is Regular Expression Object)"""
432     class_description = "Value is Python Regular Expression (UTF8-encoded)."
434     RE_TYPE = type(re.compile(""))
436     def __init__(self, config, section, setting,
437         default=NODEFAULT, description=None, aliases=None,
438         flags=0,
439     ):
440         self.flags = flags
441         Option.__init__(self, config, section, setting, default,
442             description, aliases)
444     def _value2str(self, value):
445         assert isinstance(value, self.RE_TYPE)
446         return value.pattern
448     def str2value(self, value):
449         if not isinstance(value, unicode):
450             value = str(value)
451             # if it is 7-bit ascii, use it as string,
452             # otherwise convert to unicode.
453             try:
454                 value.decode("ascii")
455             except UnicodeError:
456                 value = value.decode("utf-8")
457         return re.compile(value, self.flags)
459 ### Main configuration layout.
460 # Config is described as a sequence of sections,
461 # where each section name is followed by a sequence
462 # of Option definitions.  Each Option definition
463 # is a sequence containing class name and constructor
464 # parameters, starting from the setting name:
465 # setting, default, [description, [aliases]]
466 # Note: aliases should only exist in historical options for backwards
467 # compatibility - new options should *not* have aliases!
468 SETTINGS = (
469     ("main", (
470         (FilePathOption, "database", "db", "Database directory path."),
471         (FilePathOption, "templates", "html",
472             "Path to the HTML templates directory."),
473         (NullableFilePathOption, "static_files", "",
474             "Path to directory holding additional static files\n"
475             "available via Web UI.  This directory may contain\n"
476             "sitewide images, CSS stylesheets etc. and is searched\n"
477             "for these files prior to the TEMPLATES directory\n"
478             "specified above.  If this option is not set, all static\n"
479             "files are taken from the TEMPLATES directory"),
480         (MailAddressOption, "admin_email", "roundup-admin",
481             "Email address that roundup will complain to if it runs\n"
482             "into trouble.\n"
483             "If no domain is specified then the config item\n"
484             "mail -> domain is added."),
485         (MailAddressOption, "dispatcher_email", "roundup-admin",
486             "The 'dispatcher' is a role that can get notified\n"
487             "of new items to the database.\n"
488             "It is used by the ERROR_MESSAGES_TO config setting.\n"
489             "If no domain is specified then the config item\n"
490             "mail -> domain is added."),
491         (Option, "email_from_tag", "",
492             "Additional text to include in the \"name\" part\n"
493             "of the From: address used in nosy messages.\n"
494             "If the sending user is \"Foo Bar\", the From: line\n"
495             "is usually: \"Foo Bar\" <issue_tracker@tracker.example>\n"
496             "the EMAIL_FROM_TAG goes inside the \"Foo Bar\" quotes like so:\n"
497             "\"Foo Bar EMAIL_FROM_TAG\" <issue_tracker@tracker.example>"),
498         (Option, "new_web_user_roles", "User",
499             "Roles that a user gets when they register"
500             " with Web User Interface.\n"
501             "This is a comma-separated string of role names"
502             " (e.g. 'Admin,User')."),
503         (Option, "new_email_user_roles", "User",
504             "Roles that a user gets when they register"
505             " with Email Gateway.\n"
506             "This is a comma-separated string of role names"
507             " (e.g. 'Admin,User')."),
508         (Option, "error_messages_to", "user",
509             # XXX This description needs better wording,
510             #   with explicit allowed values list.
511             "Send error message emails to the dispatcher, user, or both?\n"
512             "The dispatcher is configured using the DISPATCHER_EMAIL"
513             " setting."),
514         (Option, "html_version", "html4",
515             "HTML version to generate. The templates are html4 by default.\n"
516             "If you wish to make them xhtml, then you'll need to change this\n"
517             "var to 'xhtml' too so all auto-generated HTML is compliant.\n"
518             "Allowed values: html4, xhtml"),
519         (TimezoneOption, "timezone", "UTC", "Default timezone offset,"
520             " applied when user's timezone is not set.",
521             ["DEFAULT_TIMEZONE"]),
522         (BooleanOption, "instant_registration", "no",
523             "Register new users instantly, or require confirmation via\n"
524             "email?"),
525         (BooleanOption, "email_registration_confirmation", "yes",
526             "Offer registration confirmation by email or only through the web?"),
527         (WordListOption, "indexer_stopwords", "",
528             "Additional stop-words for the full-text indexer specific to\n"
529             "your tracker. See the indexer source for the default list of\n"
530             "stop-words (eg. A,AND,ARE,AS,AT,BE,BUT,BY, ...)"),
531         (OctalNumberOption, "umask", "02",
532             "Defines the file creation mode mask."),
533         (IntegerNumberOption, 'csv_field_size', '131072',
534             "Maximum size of a csv-field during import. Roundups export\n"
535             "format is a csv (comma separated values) variant. The csv\n"
536             "reader has a limit on the size of individual fields\n"
537             "starting with python 2.5. Set this to a higher value if you\n"
538             "get the error 'Error: field larger than field limit' during\n"
539             "import."),
540     )),
541     ("tracker", (
542         (Option, "name", "Roundup issue tracker",
543             "A descriptive name for your roundup instance."),
544         (Option, "web", NODEFAULT,
545             "The web address that the tracker is viewable at.\n"
546             "This will be included in information"
547             " sent to users of the tracker.\n"
548             "The URL MUST include the cgi-bin part or anything else\n"
549             "that is required to get to the home page of the tracker.\n"
550             "You MUST include a trailing '/' in the URL."),
551         (MailAddressOption, "email", "issue_tracker",
552             "Email address that mail to roundup should go to.\n"
553             "If no domain is specified then mail_domain is added."),
554         (NullableOption, "language", "",
555             "Default locale name for this tracker.\n"
556             "If this option is not set, the language is determined\n"
557             "by OS environment variable LANGUAGE, LC_ALL, LC_MESSAGES,\n"
558             "or LANG, in that order of preference."),
559     )),
560     ("web", (
561         (BooleanOption, "allow_html_file", "no",
562             "Setting this option enables Roundup to serve uploaded HTML\n"
563             "file content *as HTML*. This is a potential security risk\n"
564             "and is therefore disabled by default. Set to 'yes' if you\n"
565             "trust *all* users uploading content to your tracker."),
566         (BooleanOption, 'http_auth', "yes",
567             "Whether to use HTTP Basic Authentication, if present.\n"
568             "Roundup will use either the REMOTE_USER or HTTP_AUTHORIZATION\n"
569             "variables supplied by your web server (in that order).\n"
570             "Set this option to 'no' if you do not wish to use HTTP Basic\n"
571             "Authentication in your web interface."),
572         (BooleanOption, 'use_browser_language', "yes",
573             "Whether to use HTTP Accept-Language, if present.\n"
574             "Browsers send a language-region preference list.\n"
575             "It's usually set in the client's browser or in their\n"
576             "Operating System.\n"
577             "Set this option to 'no' if you want to ignore it."),
578         (BooleanOption, "debug", "no",
579             "Setting this option makes Roundup display error tracebacks\n"
580             "in the user's browser rather than emailing them to the\n"
581             "tracker admin."),
582     )),
583     ("rdbms", (
584         (Option, 'name', 'roundup',
585             "Name of the database to use.",
586             ['MYSQL_DBNAME']),
587         (NullableOption, 'host', 'localhost',
588             "Database server host.",
589             ['MYSQL_DBHOST']),
590         (NullableOption, 'port', '',
591             "TCP port number of the database server.\n"
592             "Postgresql usually resides on port 5432 (if any),\n"
593             "for MySQL default port number is 3306.\n"
594             "Leave this option empty to use backend default"),
595         (NullableOption, 'user', 'roundup',
596             "Database user name that Roundup should use.",
597             ['MYSQL_DBUSER']),
598         (NullableOption, 'password', 'roundup',
599             "Database user password.",
600             ['MYSQL_DBPASSWORD']),
601         (NullableOption, 'read_default_file', '~/.my.cnf',
602             "Name of the MySQL defaults file.\n"
603             "Only used in MySQL connections."),
604         (NullableOption, 'read_default_group', 'roundup',
605             "Name of the group to use in the MySQL defaults file (.my.cnf).\n"
606             "Only used in MySQL connections."),
607         (IntegerNumberOption, 'sqlite_timeout', '30',
608             "Number of seconds to wait when the SQLite database is locked\n"
609             "Default: use a 30 second timeout (extraordinarily generous)\n"
610             "Only used in SQLite connections."),
611         (IntegerNumberOption, 'cache_size', '100',
612             "Size of the node cache (in elements)"),
613     ), "Settings in this section are used"
614         " by RDBMS backends only"
615     ),
616     ("logging", (
617         (FilePathOption, "config", "",
618             "Path to configuration file for standard Python logging module.\n"
619             "If this option is set, logging configuration is loaded\n"
620             "from specified file; options 'filename' and 'level'\n"
621             "in this section are ignored."),
622         (FilePathOption, "filename", "",
623             "Log file name for minimal logging facility built into Roundup.\n"
624             "If no file name specified, log messages are written on stderr.\n"
625             "If above 'config' option is set, this option has no effect."),
626         (Option, "level", "ERROR",
627             "Minimal severity level of messages written to log file.\n"
628             "If above 'config' option is set, this option has no effect.\n"
629             "Allowed values: DEBUG, INFO, WARNING, ERROR"),
630     )),
631     ("mail", (
632         (Option, "domain", NODEFAULT,
633             "The email domain that admin_email, issue_tracker and\n"
634             "dispatcher_email belong to.\n"
635             "This domain is added to those config items if they don't\n"
636             "explicitly include a domain.\n"
637             "Do not include the '@' symbol."),
638         (Option, "host", NODEFAULT,
639             "SMTP mail host that roundup will use to send mail",
640             ["MAILHOST"],),
641         (Option, "username", "", "SMTP login name.\n"
642             "Set this if your mail host requires authenticated access.\n"
643             "If username is not empty, password (below) MUST be set!"),
644         (Option, "password", NODEFAULT, "SMTP login password.\n"
645             "Set this if your mail host requires authenticated access."),
646         (IntegerNumberOption, "port", smtplib.SMTP_PORT,
647             "Default port to send SMTP on.\n"
648             "Set this if your mail server runs on a different port."),
649         (NullableOption, "local_hostname", '',
650             "The local hostname to use during SMTP transmission.\n"
651             "Set this if your mail server requires something specific."),
652         (BooleanOption, "tls", "no",
653             "If your SMTP mail host provides or requires TLS\n"
654             "(Transport Layer Security) then set this option to 'yes'."),
655         (NullableFilePathOption, "tls_keyfile", "",
656             "If TLS is used, you may set this option to the name\n"
657             "of a PEM formatted file that contains your private key."),
658         (NullableFilePathOption, "tls_certfile", "",
659             "If TLS is used, you may set this option to the name\n"
660             "of a PEM formatted certificate chain file."),
661         (Option, "charset", "utf-8",
662             "Character set to encode email headers with.\n"
663             "We use utf-8 by default, as it's the most flexible.\n"
664             "Some mail readers (eg. Eudora) can't cope with that,\n"
665             "so you might need to specify a more limited character set\n"
666             "(eg. iso-8859-1).",
667             ["EMAIL_CHARSET"]),
668         (FilePathOption, "debug", "",
669             "Setting this option makes Roundup to write all outgoing email\n"
670             "messages to this file *instead* of sending them.\n"
671             "This option has the same effect as environment variable"
672             " SENDMAILDEBUG.\nEnvironment variable takes precedence."),
673         (BooleanOption, "add_authorinfo", "yes",
674             "Add a line with author information at top of all messages\n"
675             "sent by roundup"),
676         (BooleanOption, "add_authoremail", "yes",
677             "Add the mail address of the author to the author information at\n"
678             "the top of all messages.\n"
679             "If this is false but add_authorinfo is true, only the name\n"
680             "of the actor is added which protects the mail address of the\n"
681             "actor from being exposed at mail archives, etc."),
682     ), "Outgoing email options.\nUsed for nozy messages and approval requests"),
683     ("mailgw", (
684         (BooleanOption, "keep_quoted_text", "yes",
685             "Keep email citations when accepting messages.\n"
686             "Setting this to \"no\" strips out \"quoted\" text"
687             " from the message.\n"
688             "Signatures are also stripped.",
689             ["EMAIL_KEEP_QUOTED_TEXT"]),
690         (BooleanOption, "leave_body_unchanged", "no",
691             "Preserve the email body as is - that is,\n"
692             "keep the citations _and_ signatures.",
693             ["EMAIL_LEAVE_BODY_UNCHANGED"]),
694         (Option, "default_class", "issue",
695             "Default class to use in the mailgw\n"
696             "if one isn't supplied in email subjects.\n"
697             "To disable, leave the value blank.",
698             ["MAIL_DEFAULT_CLASS"]),
699         (NullableOption, "language", "",
700             "Default locale name for the tracker mail gateway.\n"
701             "If this option is not set, mail gateway will use\n"
702             "the language of the tracker instance."),
703         (Option, "subject_prefix_parsing", "strict",
704             "Controls the parsing of the [prefix] on subject\n"
705             "lines in incoming emails. \"strict\" will return an\n"
706             "error to the sender if the [prefix] is not recognised.\n"
707             "\"loose\" will attempt to parse the [prefix] but just\n"
708             "pass it through as part of the issue title if not\n"
709             "recognised. \"none\" will always pass any [prefix]\n"
710             "through as part of the issue title."),
711         (Option, "subject_suffix_parsing", "strict",
712             "Controls the parsing of the [suffix] on subject\n"
713             "lines in incoming emails. \"strict\" will return an\n"
714             "error to the sender if the [suffix] is not recognised.\n"
715             "\"loose\" will attempt to parse the [suffix] but just\n"
716             "pass it through as part of the issue title if not\n"
717             "recognised. \"none\" will always pass any [suffix]\n"
718             "through as part of the issue title."),
719         (Option, "subject_suffix_delimiters", "[]",
720             "Defines the brackets used for delimiting the prefix and \n"
721             'suffix in a subject line. The presence of "suffix" in\n'
722             "the config option name is a historical artifact and may\n"
723             "be ignored."),
724         (Option, "subject_content_match", "always",
725             "Controls matching of the incoming email subject line\n"
726             "against issue titles in the case where there is no\n"
727             "designator [prefix]. \"never\" turns off matching.\n"
728             "\"creation + interval\" or \"activity + interval\"\n"
729             "will match an issue for the interval after the issue's\n"
730             "creation or last activity. The interval is a standard\n"
731             "Roundup interval."),
732         (BooleanOption, "subject_updates_title", "yes",
733             "Update issue title if incoming subject of email is different.\n"
734             "Setting this to \"no\" will ignore the title part of"
735             " the subject\nof incoming email messages.\n"),
736         (RegExpOption, "refwd_re", "(\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+",
737             "Regular expression matching a single reply or forward\n"
738             "prefix prepended by the mailer. This is explicitly\n"
739             "stripped from the subject during parsing."),
740         (RegExpOption, "origmsg_re",
741             "^[>|\s]*-----\s?Original Message\s?-----$",
742             "Regular expression matching start of an original message\n"
743             "if quoted the in body."),
744         (RegExpOption, "sign_re", "^[>|\s]*-- ?$",
745             "Regular expression matching the start of a signature\n"
746             "in the message body."),
747         (RegExpOption, "eol_re", r"[\r\n]+",
748             "Regular expression matching end of line."),
749         (RegExpOption, "blankline_re", r"[\r\n]+\s*[\r\n]+",
750             "Regular expression matching a blank line."),
751         (BooleanOption, "unpack_rfc822", "no",
752             "Unpack attached messages (encoded as message/rfc822 in MIME)\n"
753             "as multiple parts attached as files to the issue, if not\n"
754             "set we handle message/rfc822 attachments as a single file."),
755         (BooleanOption, "ignore_alternatives", "no",
756             "When parsing incoming mails, roundup uses the first\n"
757             "text/plain part it finds. If this part is inside a\n"
758             "multipart/alternative, and this option is set, all other\n"
759             "parts of the multipart/alternative are ignored. The default\n"
760             "is to keep all parts and attach them to the issue."),
761     ), "Roundup Mail Gateway options"),
762     ("pgp", (
763         (BooleanOption, "enable", "no",
764             "Enable PGP processing. Requires pyme."),
765         (NullableOption, "roles", "",
766             "If specified, a comma-separated list of roles to perform\n"
767             "PGP processing on. If not specified, it happens for all\n"
768             "users."),
769         (NullableOption, "homedir", "",
770             "Location of PGP directory. Defaults to $HOME/.gnupg if\n"
771             "not specified."),
772     ), "OpenPGP mail processing options"),
773     ("nosy", (
774         (RunDetectorOption, "messages_to_author", "no",
775             "Send nosy messages to the author of the message.",
776             ["MESSAGES_TO_AUTHOR"]),
777         (Option, "signature_position", "bottom",
778             "Where to place the email signature.\n"
779             "Allowed values: top, bottom, none",
780             ["EMAIL_SIGNATURE_POSITION"]),
781         (RunDetectorOption, "add_author", "new",
782             "Does the author of a message get placed on the nosy list\n"
783             "automatically?  If 'new' is used, then the author will\n"
784             "only be added when a message creates a new issue.\n"
785             "If 'yes', then the author will be added on followups too.\n"
786             "If 'no', they're never added to the nosy.\n",
787             ["ADD_AUTHOR_TO_NOSY"]),
788         (RunDetectorOption, "add_recipients", "new",
789             "Do the recipients (To:, Cc:) of a message get placed on the\n"
790             "nosy list?  If 'new' is used, then the recipients will\n"
791             "only be added when a message creates a new issue.\n"
792             "If 'yes', then the recipients will be added on followups too.\n"
793             "If 'no', they're never added to the nosy.\n",
794             ["ADD_RECIPIENTS_TO_NOSY"]),
795         (Option, "email_sending", "single",
796             "Controls the email sending from the nosy reactor. If\n"
797             "\"multiple\" then a separate email is sent to each\n"
798             "recipient. If \"single\" then a single email is sent with\n"
799             "each recipient as a CC address."),
800         (IntegerNumberOption, "max_attachment_size", sys.maxint,
801             "Attachments larger than the given number of bytes\n"
802             "won't be attached to nosy mails. They will be replaced by\n"
803             "a link to the tracker's download page for the file.")
804     ), "Nosy messages sending"),
807 ### Configuration classes
809 class Config:
811     """Base class for configuration objects.
813     Configuration options may be accessed as attributes or items
814     of instances of this class.  All option names are uppercased.
816     """
818     # Config file name
819     INI_FILE = "config.ini"
821     # Object attributes that should not be taken as common configuration
822     # options in __setattr__ (most of them are initialized in constructor):
823     # builtin pseudo-option - package home directory
824     HOME = "."
825     # names of .ini file sections, in order
826     sections = None
827     # section comments
828     section_descriptions = None
829     # lists of option names for each section, in order
830     section_options = None
831     # mapping from option names and aliases to Option instances
832     options = None
833     # actual name of the config file.  set on load.
834     filepath = os.path.join(HOME, INI_FILE)
836     def __init__(self, config_path=None, layout=None, settings={}):
837         """Initialize confing instance
839         Parameters:
840             config_path:
841                 optional directory or file name of the config file.
842                 If passed, load the config after processing layout (if any).
843                 If config_path is a directory name, use default base name
844                 of the config file.
845             layout:
846                 optional configuration layout, a sequence of
847                 section definitions suitable for .add_section()
848             settings:
849                 optional setting overrides (dictionary).
850                 The overrides are applied after loading config file.
852         """
853         # initialize option containers:
854         self.sections = []
855         self.section_descriptions = {}
856         self.section_options = {}
857         self.options = {}
858         # add options from the layout structure
859         if layout:
860             for section in layout:
861                 self.add_section(*section)
862         if config_path is not None:
863             self.load(config_path)
864         for (name, value) in settings.items():
865             self[name.upper()] = value
867     def add_section(self, section, options, description=None):
868         """Define new config section
870         Parameters:
871             section - name of the config.ini section
872             options - a sequence of Option definitions.
873                 Each Option definition is a sequence
874                 containing class object and constructor
875                 parameters, starting from the setting name:
876                 setting, default, [description, [aliases]]
877             description - optional section comment
879         Note: aliases should only exist in historical options
880         for backwards compatibility - new options should
881         *not* have aliases!
883         """
884         if description or not self.section_descriptions.has_key(section):
885             self.section_descriptions[section] = description
886         for option_def in options:
887             klass = option_def[0]
888             args = option_def[1:]
889             option = klass(self, section, *args)
890             self.add_option(option)
892     def add_option(self, option):
893         """Adopt a new Option object"""
894         _section = option.section
895         _name = option.setting
896         if _section not in self.sections:
897             self.sections.append(_section)
898         _options = self._get_section_options(_section)
899         if _name not in _options:
900             _options.append(_name)
901         # (section, name) key is used for writing .ini file
902         self.options[(_section, _name)] = option
903         # make the option known under all of its A.K.A.s
904         for _name in option.aliases:
905             self.options[_name] = option
907     def update_option(self, name, klass,
908         default=NODEFAULT, description=None
909     ):
910         """Override behaviour of early created option.
912         Parameters:
913             name:
914                 option name
915             klass:
916                 one of the Option classes
917             default:
918                 optional default value for the option
919             description:
920                 optional new description for the option
922         Conversion from current option value to new class value
923         is done via string representation.
925         This method may be used to attach some brains
926         to options autocreated by UserConfig.
928         """
929         # fetch current option
930         option = self._get_option(name)
931         # compute constructor parameters
932         if default is NODEFAULT:
933             default = option.default
934         if description is None:
935             description = option.description
936         value = option.value2str(current=1)
937         # resurrect the option
938         option = klass(self, option.section, option.setting,
939             default=default, description=description)
940         # apply the value
941         option.set(value)
942         # incorporate new option
943         del self[name]
944         self.add_option(option)
946     def reset(self):
947         """Set all options to their default values"""
948         for _option in self.items():
949             _option.reset()
951     # Meant for commandline tools.
952     # Allows automatic creation of configuration files like this:
953     #  roundup-server -p 8017 -u roundup --save-config
954     def getopt(self, args, short_options="", long_options=(),
955         config_load_options=("C", "config"), **options
956     ):
957         """Apply options specified in command line arguments.
959         Parameters:
960             args:
961                 command line to parse (sys.argv[1:])
962             short_options:
963                 optional string of letters for command line options
964                 that are not config options
965             long_options:
966                 optional list of names for long options
967                 that are not config options
968             config_load_options:
969                 two-element sequence (letter, long_option) defining
970                 the options for config file.  If unset, don't load
971                 config file; otherwise config file is read prior
972                 to applying other options.  Short option letter
973                 must not have a colon and long_option name must
974                 not have an equal sign or '--' prefix.
975             options:
976                 mapping from option names to command line option specs.
977                 e.g. server_port="p:", server_user="u:"
978                 Names are forced to lower case for commandline parsing
979                 (long options) and to upper case to find config options.
980                 Command line options accepting no value are assumed
981                 to be binary and receive value 'yes'.
983         Return value: same as for python standard getopt(), except that
984         processed options are removed from returned option list.
986         """
987         # take a copy of long_options
988         long_options = list(long_options)
989         # build option lists
990         cfg_names = {}
991         booleans = []
992         for (name, letter) in options.items():
993             cfg_name = name.upper()
994             short_opt = "-" + letter[0]
995             name = name.lower().replace("_", "-")
996             cfg_names.update({short_opt: cfg_name, "--" + name: cfg_name})
998             short_options += letter
999             if letter[-1] == ":":
1000                 long_options.append(name + "=")
1001             else:
1002                 booleans.append(short_opt)
1003                 long_options.append(name)
1005         if config_load_options:
1006             short_options += config_load_options[0] + ":"
1007             long_options.append(config_load_options[1] + "=")
1008             # compute names that will be searched in getopt return value
1009             config_load_options = (
1010                 "-" + config_load_options[0],
1011                 "--" + config_load_options[1],
1012             )
1013         # parse command line arguments
1014         optlist, args = getopt.getopt(args, short_options, long_options)
1015         # load config file if requested
1016         if config_load_options:
1017             for option in optlist:
1018                 if option[0] in config_load_options:
1019                     self.load_ini(option[1])
1020                     optlist.remove(option)
1021                     break
1022         # apply options
1023         extra_options = []
1024         for (opt, arg) in optlist:
1025             if (opt in booleans): # and not arg
1026                 arg = "yes"
1027             try:
1028                 name = cfg_names[opt]
1029             except KeyError:
1030                 extra_options.append((opt, arg))
1031             else:
1032                 self[name] = arg
1033         return (extra_options, args)
1035     # option and section locators (used in option access methods)
1037     def _get_option(self, name):
1038         try:
1039             return self.options[name]
1040         except KeyError:
1041             raise InvalidOptionError(name)
1043     def _get_section_options(self, name):
1044         return self.section_options.setdefault(name, [])
1046     def _get_unset_options(self):
1047         """Return options that need manual adjustments
1049         Return value is a dictionary where keys are section
1050         names and values are lists of option names as they
1051         appear in the config file.
1053         """
1054         need_set = {}
1055         for option in self.items():
1056             if not option.isset():
1057                 need_set.setdefault(option.section, []).append(option.setting)
1058         return need_set
1060     def _adjust_options(self, config):
1061         """Load ad-hoc option definitions from ConfigParser instance."""
1062         pass
1064     def _get_name(self):
1065         """Return the service name for config file heading"""
1066         return ""
1068     # file operations
1070     def load_ini(self, config_path, defaults=None):
1071         """Set options from config.ini file in given home_dir
1073         Parameters:
1074             config_path:
1075                 directory or file name of the config file.
1076                 If config_path is a directory name, use default
1077                 base name of the config file
1078             defaults:
1079                 optional dictionary of defaults for ConfigParser
1081         Note: if home_dir does not contain config.ini file,
1082         no error is raised.  Config will be reset to defaults.
1084         """
1085         if os.path.isdir(config_path):
1086             home_dir = config_path
1087             config_path = os.path.join(config_path, self.INI_FILE)
1088         else:
1089             home_dir = os.path.dirname(config_path)
1090         # parse the file
1091         config_defaults = {"HOME": home_dir}
1092         if defaults:
1093             config_defaults.update(defaults)
1094         config = ConfigParser.ConfigParser(config_defaults)
1095         config.read([config_path])
1096         # .ini file loaded ok.
1097         self.HOME = home_dir
1098         self.filepath = config_path
1099         self._adjust_options(config)
1100         # set the options, starting from HOME
1101         self.reset()
1102         for option in self.items():
1103             option.load_ini(config)
1105     def load(self, home_dir):
1106         """Load configuration settings from home_dir"""
1107         self.load_ini(home_dir)
1109     def save(self, ini_file=None):
1110         """Write current configuration to .ini file
1112         'ini_file' argument, if passed, must be valid full path
1113         to the file to write.  If omitted, default file in current
1114         HOME is created.
1116         If the file to write already exists, it is saved with '.bak'
1117         extension.
1119         """
1120         if ini_file is None:
1121             ini_file = self.filepath
1122         _tmp_file = os.path.splitext(ini_file)[0]
1123         _bak_file = _tmp_file + ".bak"
1124         _tmp_file = _tmp_file + ".tmp"
1125         _fp = file(_tmp_file, "wt")
1126         _fp.write("# %s configuration file\n" % self._get_name())
1127         _fp.write("# Autogenerated at %s\n" % time.asctime())
1128         need_set = self._get_unset_options()
1129         if need_set:
1130             _fp.write("\n# WARNING! Following options need adjustments:\n")
1131             for section, options in need_set.items():
1132                 _fp.write("#  [%s]: %s\n" % (section, ", ".join(options)))
1133         for section in self.sections:
1134             comment = self.section_descriptions.get(section, None)
1135             if comment:
1136                 _fp.write("\n# ".join([""] + comment.split("\n")) +"\n")
1137             else:
1138                 # no section comment - just leave a blank line between sections
1139                 _fp.write("\n")
1140             _fp.write("[%s]\n" % section)
1141             for option in self._get_section_options(section):
1142                 _fp.write("\n" + self.options[(section, option)].format())
1143         _fp.close()
1144         if os.access(ini_file, os.F_OK):
1145             if os.access(_bak_file, os.F_OK):
1146                 os.remove(_bak_file)
1147             os.rename(ini_file, _bak_file)
1148         os.rename(_tmp_file, ini_file)
1150     # container emulation
1152     def __len__(self):
1153         return len(self.items())
1155     def __getitem__(self, name):
1156         if name == "HOME":
1157             return self.HOME
1158         else:
1159             return self._get_option(name).get()
1161     def __setitem__(self, name, value):
1162         if name == "HOME":
1163             self.HOME = value
1164         else:
1165             self._get_option(name).set(value)
1167     def __delitem__(self, name):
1168         _option = self._get_option(name)
1169         _section = _option.section
1170         _name = _option.setting
1171         self._get_section_options(_section).remove(_name)
1172         del self.options[(_section, _name)]
1173         for _alias in _option.aliases:
1174             del self.options[_alias]
1176     def items(self):
1177         """Return the list of Option objects, in .ini file order
1179         Note that HOME is not included in this list
1180         because it is builtin pseudo-option, not a real Option
1181         object loaded from or saved to .ini file.
1183         """
1184         return [self.options[(_section, _name)]
1185             for _section in self.sections
1186             for _name in self._get_section_options(_section)
1187         ]
1189     def keys(self):
1190         """Return the list of "canonical" names of the options
1192         Unlike .items(), this list also includes HOME
1194         """
1195         return ["HOME"] + [_option.name for _option in self.items()]
1197     # .values() is not implemented because i am not sure what should be
1198     # the values returned from this method: Option instances or config values?
1200     # attribute emulation
1202     def __setattr__(self, name, value):
1203         if self.__dict__.has_key(name) or hasattr(self.__class__, name):
1204             self.__dict__[name] = value
1205         else:
1206             self._get_option(name).set(value)
1208     # Note: __getattr__ is not symmetric to __setattr__:
1209     #   self.__dict__ lookup is done before calling this method
1210     def __getattr__(self, name):
1211         return self[name]
1213 class UserConfig(Config):
1215     """Configuration for user extensions.
1217     Instances of this class have no predefined configuration layout.
1218     Options are created on the fly for each setting present in the
1219     config file.
1221     """
1223     def _adjust_options(self, config):
1224         # config defaults appear in all sections.
1225         # we'll need to filter them out.
1226         defaults = config.defaults().keys()
1227         # see what options are already defined and add missing ones
1228         preset = [(option.section, option.setting) for option in self.items()]
1229         for section in config.sections():
1230             for name in config.options(section):
1231                 if ((section, name) not in preset) \
1232                 and (name not in defaults):
1233                     self.add_option(Option(self, section, name))
1235 class CoreConfig(Config):
1237     """Roundup instance configuration.
1239     Core config has a predefined layout (see the SETTINGS structure),
1240     supports loading of old-style pythonic configurations and holds
1241     three additional attributes:
1242         logging:
1243             instance logging engine, from standard python logging module
1244             or minimalistic logger implemented in Roundup
1245         detectors:
1246             user-defined configuration for detectors
1247         ext:
1248             user-defined configuration for extensions
1250     """
1252     # module name for old style configuration
1253     PYCONFIG = "config"
1254     # user configs
1255     ext = None
1256     detectors = None
1258     def __init__(self, home_dir=None, settings={}):
1259         Config.__init__(self, home_dir, layout=SETTINGS, settings=settings)
1260         # load the config if home_dir given
1261         if home_dir is None:
1262             self.init_logging()
1264     def copy(self):
1265         new = CoreConfig()
1266         new.sections = list(self.sections)
1267         new.section_descriptions = dict(self.section_descriptions)
1268         new.section_options = dict(self.section_options)
1269         new.options = dict(self.options)
1270         return new
1272     def _get_unset_options(self):
1273         need_set = Config._get_unset_options(self)
1274         # remove MAIL_PASSWORD if MAIL_USER is empty
1275         if "password" in need_set.get("mail", []):
1276             if not self["MAIL_USERNAME"]:
1277                 settings = need_set["mail"]
1278                 settings.remove("password")
1279                 if not settings:
1280                     del need_set["mail"]
1281         return need_set
1283     def _get_name(self):
1284         return self["TRACKER_NAME"]
1286     def reset(self):
1287         Config.reset(self)
1288         if self.ext:
1289             self.ext.reset()
1290         if self.detectors:
1291             self.detectors.reset()
1292         self.init_logging()
1294     def init_logging(self):
1295         _file = self["LOGGING_CONFIG"]
1296         if _file and os.path.isfile(_file):
1297             logging.config.fileConfig(_file)
1298             return
1300         _file = self["LOGGING_FILENAME"]
1301         # set file & level on the roundup logger
1302         logger = logging.getLogger('roundup')
1303         if _file:
1304             hdlr = logging.FileHandler(_file)
1305         else:
1306             hdlr = logging.StreamHandler(sys.stdout)
1307         formatter = logging.Formatter(
1308             '%(asctime)s %(levelname)s %(message)s')
1309         hdlr.setFormatter(formatter)
1310         # no logging API to remove all existing handlers!?!
1311         for h in logger.handlers:
1312             h.close()
1313             logger.removeHandler(hdlr)
1314         logger.handlers = [hdlr]
1315         logger.setLevel(logging._levelNames[self["LOGGING_LEVEL"] or "ERROR"])
1317     def load(self, home_dir):
1318         """Load configuration from path designated by home_dir argument"""
1319         if os.path.isfile(os.path.join(home_dir, self.INI_FILE)):
1320             self.load_ini(home_dir)
1321         else:
1322             self.load_pyconfig(home_dir)
1323         self.init_logging()
1324         self.ext = UserConfig(os.path.join(home_dir, "extensions"))
1325         self.detectors = UserConfig(os.path.join(home_dir, "detectors"))
1327     def load_ini(self, home_dir, defaults=None):
1328         """Set options from config.ini file in given home_dir directory"""
1329         config_defaults = {"TRACKER_HOME": home_dir}
1330         if defaults:
1331             config_defaults.update(defaults)
1332         Config.load_ini(self, home_dir, config_defaults)
1334     def load_pyconfig(self, home_dir):
1335         """Set options from config.py file in given home_dir directory"""
1336         # try to locate and import the module
1337         _mod_fp = None
1338         try:
1339             try:
1340                 _module = imp.find_module(self.PYCONFIG, [home_dir])
1341                 _mod_fp = _module[0]
1342                 _config = imp.load_module(self.PYCONFIG, *_module)
1343             except ImportError:
1344                 raise NoConfigError(home_dir)
1345         finally:
1346             if _mod_fp is not None:
1347                 _mod_fp.close()
1348         # module loaded ok.  set the options, starting from HOME
1349         self.reset()
1350         self.HOME = home_dir
1351         for _option in self.items():
1352             _option.load_pyconfig(_config)
1353         # backward compatibility:
1354         # SMTP login parameters were specified as a tuple in old style configs
1355         # convert them to new plain string options
1356         _mailuser = getattr(_config, "MAILUSER", ())
1357         if len(_mailuser) > 0:
1358             self.MAIL_USERNAME = _mailuser[0]
1359         if len(_mailuser) > 1:
1360             self.MAIL_PASSWORD = _mailuser[1]
1362     # in this config, HOME is also known as TRACKER_HOME
1363     def __getitem__(self, name):
1364         if name == "TRACKER_HOME":
1365             return self.HOME
1366         else:
1367             return Config.__getitem__(self, name)
1369     def __setitem__(self, name, value):
1370         if name == "TRACKER_HOME":
1371             self.HOME = value
1372         else:
1373             self._get_option(name).set(value)
1375     def __setattr__(self, name, value):
1376         if name == "TRACKER_HOME":
1377             self.__dict__["HOME"] = value
1378         else:
1379             Config.__setattr__(self, name, value)
1381 # vim: set et sts=4 sw=4 :