roundup/admin.py

   1 #! /usr/bin/env python
   2 #
   3 # Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)
   4 # This module is free software, and you may redistribute it and/or modify
   5 # under the same terms as Python, so long as this copyright message and
   6 # disclaimer are retained in their original form.
   7 #
   8 # IN NO EVENT SHALL BIZAR SOFTWARE PTY LTD BE LIABLE TO ANY PARTY FOR
   9 # DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
  10 # OUT OF THE USE OF THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
  11 # POSSIBILITY OF SUCH DAMAGE.
  12 #
  13 # BIZAR SOFTWARE PTY LTD SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  14 # BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  15 # FOR A PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS"
  16 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
  17 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  18 #
  19 # $Id: admin.py,v 1.41 2003-03-06 06:06:49 richard Exp $
  20
  21 '''Administration commands for maintaining Roundup trackers.
  22 '''
  23
  24 import sys, os, getpass, getopt, re, UserDict, shlex, shutil
  25 try:
  26     import csv
  27 except ImportError:
  28     csv = None
  29 from roundup import date, hyperdb, roundupdb, init, password, token
  30 from roundup import __version__ as roundup_version
  31 import roundup.instance
  32 from roundup.i18n import _
  33
  34 class CommandDict(UserDict.UserDict):
  35     '''Simple dictionary that lets us do lookups using partial keys.
  36
  37     Original code submitted by Engelbert Gruber.
  38     '''
  39     _marker = []
  40     def get(self, key, default=_marker):
  41         if self.data.has_key(key):
  42             return [(key, self.data[key])]
  43         keylist = self.data.keys()
  44         keylist.sort()
  45         l = []
  46         for ki in keylist:
  47             if ki.startswith(key):
  48                 l.append((ki, self.data[ki]))
  49         if not l and default is self._marker:
  50             raise KeyError, key
  51         return l
  52
  53 class UsageError(ValueError):
  54     pass
  55
  56 class AdminTool:
  57     ''' A collection of methods used in maintaining Roundup trackers.
  58
  59         Typically these methods are accessed through the roundup-admin
  60         script. The main() method provided on this class gives the main
  61         loop for the roundup-admin script.
  62
  63         Actions are defined by do_*() methods, with help for the action
  64         given in the method docstring.
  65
  66         Additional help may be supplied by help_*() methods.
  67     '''
  68     def __init__(self):
  69         self.commands = CommandDict()
  70         for k in AdminTool.__dict__.keys():
  71             if k[:3] == 'do_':
  72                 self.commands[k[3:]] = getattr(self, k)
  73         self.help = {}
  74         for k in AdminTool.__dict__.keys():
  75             if k[:5] == 'help_':
  76                 self.help[k[5:]] = getattr(self, k)
  77         self.tracker_home = ''
  78         self.db = None
  79
  80     def get_class(self, classname):
  81         '''Get the class - raise an exception if it doesn't exist.
  82         '''
  83         try:
  84             return self.db.getclass(classname)
  85         except KeyError:
  86             raise UsageError, _('no such class "%(classname)s"')%locals()
  87
  88     def props_from_args(self, args):
  89         ''' Produce a dictionary of prop: value from the args list.
  90
  91             The args list is specified as ``prop=value prop=value ...``.
  92         '''
  93         props = {}
  94         for arg in args:
  95             if arg.find('=') == -1:
  96                 raise UsageError, _('argument "%(arg)s" not propname=value'
  97                     )%locals()
  98             try:
  99                 key, value = arg.split('=')
 100             except ValueError:
 101                 raise UsageError, _('argument "%(arg)s" not propname=value'
 102                     )%locals()
 103             if value:
 104                 props[key] = value
 105             else:
 106                 props[key] = None
 107         return props
 108
 109     def usage(self, message=''):
 110         ''' Display a simple usage message.
 111         '''
 112         if message:
 113             message = _('Problem: %(message)s)\n\n')%locals()
 114         print _('''%(message)sUsage: roundup-admin [options] <command> <arguments>
 115
 116 Options:
 117  -i instance home  -- specify the issue tracker "home directory" to administer
 118  -u                -- the user[:password] to use for commands
 119  -c                -- when outputting lists of data, just comma-separate them
 120
 121 Help:
 122  roundup-admin -h
 123  roundup-admin help                       -- this help
 124  roundup-admin help <command>             -- command-specific help
 125  roundup-admin help all                   -- all available help
 126 ''')%locals()
 127         self.help_commands()
 128
 129     def help_commands(self):
 130         ''' List the commands available with their precis help.
 131         '''
 132         print _('Commands:'),
 133         commands = ['']
 134         for command in self.commands.values():
 135             h = command.__doc__.split('\n')[0]
 136             commands.append(' '+h[7:])
 137         commands.sort()
 138         commands.append(_('Commands may be abbreviated as long as the abbreviation matches only one'))
 139         commands.append(_('command, e.g. l == li == lis == list.'))
 140         print '\n'.join(commands)
 141         print
 142
 143     def help_commands_html(self, indent_re=re.compile(r'^(\s+)\S+')):
 144         ''' Produce an HTML command list.
 145         '''
 146         commands = self.commands.values()
 147         def sortfun(a, b):
 148             return cmp(a.__name__, b.__name__)
 149         commands.sort(sortfun)
 150         for command in commands:
 151             h = command.__doc__.split('\n')
 152             name = command.__name__[3:]
 153             usage = h[0]
 154             print _('''
 155 <tr><td valign=top><strong>%(name)s</strong></td>
 156     <td><tt>%(usage)s</tt><p>
 157 <pre>''')%locals()
 158             indent = indent_re.match(h[3])
 159             if indent: indent = len(indent.group(1))
 160             for line in h[3:]:
 161                 if indent:
 162                     print line[indent:]
 163                 else:
 164                     print line
 165             print _('</pre></td></tr>\n')
 166
 167     def help_all(self):
 168         print _('''
 169 All commands (except help) require a tracker specifier. This is just the path
 170 to the roundup tracker you're working with. A roundup tracker is where
 171 roundup keeps the database and configuration file that defines an issue
 172 tracker. It may be thought of as the issue tracker's "home directory". It may
 173 be specified in the environment variable TRACKER_HOME or on the command
 174 line as "-i tracker".
 175
 176 A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
 177
 178 Property values are represented as strings in command arguments and in the
 179 printed results:
 180  . Strings are, well, strings.
 181  . Date values are printed in the full date format in the local time zone, and
 182    accepted in the full format or any of the partial formats explained below.
 183  . Link values are printed as node designators. When given as an argument,
 184    node designators and key strings are both accepted.
 185  . Multilink values are printed as lists of node designators joined by commas.
 186    When given as an argument, node designators and key strings are both
 187    accepted; an empty string, a single node, or a list of nodes joined by
 188    commas is accepted.
 189
 190 When property values must contain spaces, just surround the value with
 191 quotes, either ' or ". A single space may also be backslash-quoted. If a
 192 valuu must contain a quote character, it must be backslash-quoted or inside
 193 quotes. Examples:
 194            hello world      (2 tokens: hello, world)
 195            "hello world"    (1 token: hello world)
 196            "Roch'e" Compaan (2 tokens: Roch'e Compaan)
 197            Roch\'e Compaan  (2 tokens: Roch'e Compaan)
 198            address="1 2 3"  (1 token: address=1 2 3)
 199            \\               (1 token: \)
 200            \n\r\t           (1 token: a newline, carriage-return and tab)
 201
 202 When multiple nodes are specified to the roundup get or roundup set
 203 commands, the specified properties are retrieved or set on all the listed
 204 nodes.
 205
 206 When multiple results are returned by the roundup get or roundup find
 207 commands, they are printed one per line (default) or joined by commas (with
 208 the -c) option.
 209
 210 Where the command changes data, a login name/password is required. The
 211 login may be specified as either "name" or "name:password".
 212  . ROUNDUP_LOGIN environment variable
 213  . the -u command-line option
 214 If either the name or password is not supplied, they are obtained from the
 215 command-line.
 216
 217 Date format examples:
 218   "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
 219   "2000-04-17" means <Date 2000-04-17.00:00:00>
 220   "01-25" means <Date yyyy-01-25.00:00:00>
 221   "08-13.22:13" means <Date yyyy-08-14.03:13:00>
 222   "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
 223   "14:25" means <Date yyyy-mm-dd.19:25:00>
 224   "8:47:11" means <Date yyyy-mm-dd.13:47:11>
 225   "." means "right now"
 226
 227 Command help:
 228 ''')
 229         for name, command in self.commands.items():
 230             print _('%s:')%name
 231             print _('   '), command.__doc__
 232
 233     def do_help(self, args, nl_re=re.compile('[\r\n]'),
 234             indent_re=re.compile(r'^(\s+)\S+')):
 235         '''Usage: help topic
 236         Give help about topic.
 237
 238         commands  -- list commands
 239         <command> -- help specific to a command
 240         initopts  -- init command options
 241         all       -- all available help
 242         '''
 243         if len(args)>0:
 244             topic = args[0]
 245         else:
 246             topic = 'help'
 247
 248
 249         # try help_ methods
 250         if self.help.has_key(topic):
 251             self.help[topic]()
 252             return 0
 253
 254         # try command docstrings
 255         try:
 256             l = self.commands.get(topic)
 257         except KeyError:
 258             print _('Sorry, no help for "%(topic)s"')%locals()
 259             return 1
 260
 261         # display the help for each match, removing the docsring indent
 262         for name, help in l:
 263             lines = nl_re.split(help.__doc__)
 264             print lines[0]
 265             indent = indent_re.match(lines[1])
 266             if indent: indent = len(indent.group(1))
 267             for line in lines[1:]:
 268                 if indent:
 269                     print line[indent:]
 270                 else:
 271                     print line
 272         return 0
 273
 274     def help_initopts(self):
 275         import roundup.templates
 276         templates = roundup.templates.listTemplates()
 277         print _('Templates:'), ', '.join(templates)
 278         import roundup.backends
 279         backends = roundup.backends.__all__
 280         print _('Back ends:'), ', '.join(backends)
 281
 282     def do_install(self, tracker_home, args):
 283         '''Usage: install [template [backend [admin password]]]
 284         Install a new Roundup tracker.
 285
 286         The command will prompt for the tracker home directory (if not supplied
 287         through TRACKER_HOME or the -i option). The template, backend and admin
 288         password may be specified on the command-line as arguments, in that
 289         order.
 290
 291         The initialise command must be called after this command in order
 292         to initialise the tracker's database. You may edit the tracker's
 293         initial database contents before running that command by editing
 294         the tracker's dbinit.py module init() function.
 295
 296         See also initopts help.
 297         '''
 298         if len(args) < 1:
 299             raise UsageError, _('Not enough arguments supplied')
 300
 301         # make sure the tracker home can be created
 302         parent = os.path.split(tracker_home)[0]
 303         if not os.path.exists(parent):
 304             raise UsageError, _('Instance home parent directory "%(parent)s"'
 305                 ' does not exist')%locals()
 306
 307         # select template
 308         import roundup.templates
 309         templates = roundup.templates.listTemplates()
 310         template = len(args) > 1 and args[1] or ''
 311         if template not in templates:
 312             print _('Templates:'), ', '.join(templates)
 313         while template not in templates:
 314             template = raw_input(_('Select template [classic]: ')).strip()
 315             if not template:
 316                 template = 'classic'
 317
 318         # select hyperdb backend
 319         import roundup.backends
 320         backends = roundup.backends.__all__
 321         backend = len(args) > 2 and args[2] or ''
 322         if backend not in backends:
 323             print _('Back ends:'), ', '.join(backends)
 324         while backend not in backends:
 325             backend = raw_input(_('Select backend [anydbm]: ')).strip()
 326             if not backend:
 327                 backend = 'anydbm'
 328         # XXX perform a unit test based on the user's selections
 329
 330         # install!
 331         init.install(tracker_home, template)
 332         init.write_select_db(tracker_home, backend)
 333
 334         print _('''
 335  You should now edit the tracker configuration file:
 336    %(config_file)s
 337  ... at a minimum, you must set MAILHOST, TRACKER_WEB, MAIL_DOMAIN and
 338  ADMIN_EMAIL.
 339
 340  If you wish to modify the default schema, you should also edit the database
 341  initialisation file:
 342    %(database_config_file)s
 343  ... see the documentation on customizing for more information.
 344 ''')%{
 345     'config_file': os.path.join(tracker_home, 'config.py'),
 346     'database_config_file': os.path.join(tracker_home, 'dbinit.py')
 347 }
 348         return 0
 349
 350
 351     def do_initialise(self, tracker_home, args):
 352         '''Usage: initialise [adminpw]
 353         Initialise a new Roundup tracker.
 354
 355         The administrator details will be set at this step.
 356
 357         Execute the tracker's initialisation function dbinit.init()
 358         '''
 359         # password
 360         if len(args) > 1:
 361             adminpw = args[1]
 362         else:
 363             adminpw = ''
 364             confirm = 'x'
 365             while adminpw != confirm:
 366                 adminpw = getpass.getpass(_('Admin Password: '))
 367                 confirm = getpass.getpass(_('       Confirm: '))
 368
 369         # make sure the tracker home is installed
 370         if not os.path.exists(tracker_home):
 371             raise UsageError, _('Instance home does not exist')%locals()
 372         try:
 373             tracker = roundup.instance.open(tracker_home)
 374         except roundup.instance.TrackerError:
 375             raise UsageError, _('Instance has not been installed')%locals()
 376
 377         # is there already a database?
 378         try:
 379             db_exists = tracker.select_db.Database.exists(tracker.config)
 380         except AttributeError:
 381             # TODO: move this code to exists() static method in every backend
 382             db_exists = os.path.exists(os.path.join(tracker_home, 'db'))
 383         if db_exists:
 384             print _('WARNING: The database is already initialised!')
 385             print _('If you re-initialise it, you will lose all the data!')
 386             ok = raw_input(_('Erase it? Y/[N]: ')).strip()
 387             if ok.lower() != 'y':
 388                 return 0
 389
 390             # Get a database backend in use by tracker
 391             try:
 392                 # nuke it
 393                 tracker.select_db.Database.nuke(tracker.config)
 394             except AttributeError:
 395                 # TODO: move this code to nuke() static method in every backend
 396                 shutil.rmtree(os.path.join(tracker_home, 'db'))
 397
 398         # GO
 399         init.initialise(tracker_home, adminpw)
 400
 401         return 0
 402
 403
 404     def do_get(self, args):
 405         '''Usage: get property designator[,designator]*
 406         Get the given property of one or more designator(s).
 407
 408         Retrieves the property value of the nodes specified by the designators.
 409         '''
 410         if len(args) < 2:
 411             raise UsageError, _('Not enough arguments supplied')
 412         propname = args[0]
 413         designators = args[1].split(',')
 414         l = []
 415         for designator in designators:
 416             # decode the node designator
 417             try:
 418                 classname, nodeid = hyperdb.splitDesignator(designator)
 419             except hyperdb.DesignatorError, message:
 420                 raise UsageError, message
 421
 422             # get the class
 423             cl = self.get_class(classname)
 424             try:
 425                 if self.comma_sep:
 426                     l.append(cl.get(nodeid, propname))
 427                 else:
 428                     print cl.get(nodeid, propname)
 429             except IndexError:
 430                 raise UsageError, _('no such %(classname)s node "%(nodeid)s"')%locals()
 431             except KeyError:
 432                 raise UsageError, _('no such %(classname)s property '
 433                     '"%(propname)s"')%locals()
 434         if self.comma_sep:
 435             print ','.join(l)
 436         return 0
 437
 438
 439     def do_set(self, args, pwre = re.compile(r'{(\w+)}(.+)')):
 440         '''Usage: set [items] property=value property=value ...
 441         Set the given properties of one or more items(s).
 442
 443         The items may be specified as a class or as a comma-separeted
 444         list of item designators (ie "designator[,designator,...]").
 445
 446         This command sets the properties to the values for all designators
 447         given. If the value is missing (ie. "property=") then the property is
 448         un-set. If the property is a multilink, you specify the linked ids
 449         for the multilink as comma-separated numbers (ie "1,2,3").
 450         '''
 451         if len(args) < 2:
 452             raise UsageError, _('Not enough arguments supplied')
 453         from roundup import hyperdb
 454
 455         designators = args[0].split(',')
 456         if len(designators) == 1:
 457             designator = designators[0]
 458             try:
 459                 designator = hyperdb.splitDesignator(designator)
 460                 designators = [designator]
 461             except hyperdb.DesignatorError:
 462                 cl = self.get_class(designator)
 463                 designators = [(designator, x) for x in cl.list()]
 464         else:
 465             try:
 466                 designators = [hyperdb.splitDesignator(x) for x in designators]
 467             except hyperdb.DesignatorError, message:
 468                 raise UsageError, message
 469
 470         # get the props from the args
 471         props = self.props_from_args(args[1:])
 472
 473         # now do the set for all the nodes
 474         for classname, itemid in designators:
 475             cl = self.get_class(classname)
 476
 477             properties = cl.getprops()
 478             for key, value in props.items():
 479                 proptype =  properties[key]
 480                 if isinstance(proptype, hyperdb.Multilink):
 481                     if value is None:
 482                         props[key] = []
 483                     else:
 484                         props[key] = value.split(',')
 485                 elif value is None:
 486                     continue
 487                 elif isinstance(proptype, hyperdb.String):
 488                     continue
 489                 elif isinstance(proptype, hyperdb.Password):
 490                     m = pwre.match(value)
 491                     if m:
 492                         # password is being given to us encrypted
 493                         p = password.Password()
 494                         p.scheme = m.group(1)
 495                         p.password = m.group(2)
 496                         props[key] = p
 497                     else:
 498                         props[key] = password.Password(value)
 499                 elif isinstance(proptype, hyperdb.Date):
 500                     try:
 501                         props[key] = date.Date(value)
 502                     except ValueError, message:
 503                         raise UsageError, '"%s": %s'%(value, message)
 504                 elif isinstance(proptype, hyperdb.Interval):
 505                     try:
 506                         props[key] = date.Interval(value)
 507                     except ValueError, message:
 508                         raise UsageError, '"%s": %s'%(value, message)
 509                 elif isinstance(proptype, hyperdb.Link):
 510                     props[key] = value
 511                 elif isinstance(proptype, hyperdb.Boolean):
 512                     props[key] = value.lower() in ('yes', 'true', 'on', '1')
 513                 elif isinstance(proptype, hyperdb.Number):
 514                     props[key] = float(value)
 515
 516             # try the set
 517             try:
 518                 apply(cl.set, (itemid, ), props)
 519             except (TypeError, IndexError, ValueError), message:
 520                 import traceback; traceback.print_exc()
 521                 raise UsageError, message
 522         return 0
 523
 524     def do_find(self, args):
 525         '''Usage: find classname propname=value ...
 526         Find the nodes of the given class with a given link property value.
 527
 528         Find the nodes of the given class with a given link property value. The
 529         value may be either the nodeid of the linked node, or its key value.
 530         '''
 531         if len(args) < 1:
 532             raise UsageError, _('Not enough arguments supplied')
 533         classname = args[0]
 534         # get the class
 535         cl = self.get_class(classname)
 536
 537         # handle the propname=value argument
 538         props = self.props_from_args(args[1:])
 539
 540         # if the value isn't a number, look up the linked class to get the
 541         # number
 542         for propname, value in props.items():
 543             num_re = re.compile('^\d+$')
 544             if not num_re.match(value):
 545                 # get the property
 546                 try:
 547                     property = cl.properties[propname]
 548                 except KeyError:
 549                     raise UsageError, _('%(classname)s has no property '
 550                         '"%(propname)s"')%locals()
 551
 552                 # make sure it's a link
 553                 if (not isinstance(property, hyperdb.Link) and not
 554                         isinstance(property, hyperdb.Multilink)):
 555                     raise UsageError, _('You may only "find" link properties')
 556
 557                 # get the linked-to class and look up the key property
 558                 link_class = self.db.getclass(property.classname)
 559                 try:
 560                     props[propname] = link_class.lookup(value)
 561                 except TypeError:
 562                     raise UsageError, _('%(classname)s has no key property"')%{
 563                         'classname': link_class.classname}
 564
 565         # now do the find
 566         try:
 567             if self.comma_sep:
 568                 print ','.join(apply(cl.find, (), props))
 569             else:
 570                 print apply(cl.find, (), props)
 571         except KeyError:
 572             raise UsageError, _('%(classname)s has no property '
 573                 '"%(propname)s"')%locals()
 574         except (ValueError, TypeError), message:
 575             raise UsageError, message
 576         return 0
 577
 578     def do_specification(self, args):
 579         '''Usage: specification classname
 580         Show the properties for a classname.
 581
 582         This lists the properties for a given class.
 583         '''
 584         if len(args) < 1:
 585             raise UsageError, _('Not enough arguments supplied')
 586         classname = args[0]
 587         # get the class
 588         cl = self.get_class(classname)
 589
 590         # get the key property
 591         keyprop = cl.getkey()
 592         for key, value in cl.properties.items():
 593             if keyprop == key:
 594                 print _('%(key)s: %(value)s (key property)')%locals()
 595             else:
 596                 print _('%(key)s: %(value)s')%locals()
 597
 598     def do_display(self, args):
 599         '''Usage: display designator
 600         Show the property values for the given node.
 601
 602         This lists the properties and their associated values for the given
 603         node.
 604         '''
 605         if len(args) < 1:
 606             raise UsageError, _('Not enough arguments supplied')
 607
 608         # decode the node designator
 609         try:
 610             classname, nodeid = hyperdb.splitDesignator(args[0])
 611         except hyperdb.DesignatorError, message:
 612             raise UsageError, message
 613
 614         # get the class
 615         cl = self.get_class(classname)
 616
 617         # display the values
 618         for key in cl.properties.keys():
 619             value = cl.get(nodeid, key)
 620             print _('%(key)s: %(value)s')%locals()
 621
 622     def do_create(self, args, pwre = re.compile(r'{(\w+)}(.+)')):
 623         '''Usage: create classname property=value ...
 624         Create a new entry of a given class.
 625
 626         This creates a new entry of the given class using the property
 627         name=value arguments provided on the command line after the "create"
 628         command.
 629         '''
 630         if len(args) < 1:
 631             raise UsageError, _('Not enough arguments supplied')
 632         from roundup import hyperdb
 633
 634         classname = args[0]
 635
 636         # get the class
 637         cl = self.get_class(classname)
 638
 639         # now do a create
 640         props = {}
 641         properties = cl.getprops(protected = 0)
 642         if len(args) == 1:
 643             # ask for the properties
 644             for key, value in properties.items():
 645                 if key == 'id': continue
 646                 name = value.__class__.__name__
 647                 if isinstance(value , hyperdb.Password):
 648                     again = None
 649                     while value != again:
 650                         value = getpass.getpass(_('%(propname)s (Password): ')%{
 651                             'propname': key.capitalize()})
 652                         again = getpass.getpass(_('   %(propname)s (Again): ')%{
 653                             'propname': key.capitalize()})
 654                         if value != again: print _('Sorry, try again...')
 655                     if value:
 656                         props[key] = value
 657                 else:
 658                     value = raw_input(_('%(propname)s (%(proptype)s): ')%{
 659                         'propname': key.capitalize(), 'proptype': name})
 660                     if value:
 661                         props[key] = value
 662         else:
 663             props = self.props_from_args(args[1:])
 664
 665         # convert types
 666         for propname, value in props.items():
 667             # get the property
 668             try:
 669                 proptype = properties[propname]
 670             except KeyError:
 671                 raise UsageError, _('%(classname)s has no property '
 672                     '"%(propname)s"')%locals()
 673
 674             if isinstance(proptype, hyperdb.Date):
 675                 try:
 676                     props[propname] = date.Date(value)
 677                 except ValueError, message:
 678                     raise UsageError, _('"%(value)s": %(message)s')%locals()
 679             elif isinstance(proptype, hyperdb.Interval):
 680                 try:
 681                     props[propname] = date.Interval(value)
 682                 except ValueError, message:
 683                     raise UsageError, _('"%(value)s": %(message)s')%locals()
 684             elif isinstance(proptype, hyperdb.Password):
 685                 m = pwre.match(value)
 686                 if m:
 687                     # password is being given to us encrypted
 688                     p = password.Password()
 689                     p.scheme = m.group(1)
 690                     p.password = m.group(2)
 691                     props[propname] = p
 692                 else:
 693                     props[propname] = password.Password(value)
 694             elif isinstance(proptype, hyperdb.Multilink):
 695                 props[propname] = value.split(',')
 696             elif isinstance(proptype, hyperdb.Boolean):
 697                 props[propname] = value.lower() in ('yes', 'true', 'on', '1')
 698             elif isinstance(proptype, hyperdb.Number):
 699                 props[propname] = float(value)
 700
 701         # check for the key property
 702         propname = cl.getkey()
 703         if propname and not props.has_key(propname):
 704             raise UsageError, _('you must provide the "%(propname)s" '
 705                 'property.')%locals()
 706
 707         # do the actual create
 708         try:
 709             print apply(cl.create, (), props)
 710         except (TypeError, IndexError, ValueError), message:
 711             raise UsageError, message
 712         return 0
 713
 714     def do_list(self, args):
 715         '''Usage: list classname [property]
 716         List the instances of a class.
 717
 718         Lists all instances of the given class. If the property is not
 719         specified, the  "label" property is used. The label property is tried
 720         in order: the key, "name", "title" and then the first property,
 721         alphabetically.
 722         '''
 723         if len(args) < 1:
 724             raise UsageError, _('Not enough arguments supplied')
 725         classname = args[0]
 726
 727         # get the class
 728         cl = self.get_class(classname)
 729
 730         # figure the property
 731         if len(args) > 1:
 732             propname = args[1]
 733         else:
 734             propname = cl.labelprop()
 735
 736         if self.comma_sep:
 737             print ','.join(cl.list())
 738         else:
 739             for nodeid in cl.list():
 740                 try:
 741                     value = cl.get(nodeid, propname)
 742                 except KeyError:
 743                     raise UsageError, _('%(classname)s has no property '
 744                         '"%(propname)s"')%locals()
 745                 print _('%(nodeid)4s: %(value)s')%locals()
 746         return 0
 747
 748     def do_table(self, args):
 749         '''Usage: table classname [property[,property]*]
 750         List the instances of a class in tabular form.
 751
 752         Lists all instances of the given class. If the properties are not
 753         specified, all properties are displayed. By default, the column widths
 754         are the width of the property names. The width may be explicitly defined
 755         by defining the property as "name:width". For example::
 756           roundup> table priority id,name:10
 757           Id Name
 758           1  fatal-bug
 759           2  bug
 760           3  usability
 761           4  feature
 762         '''
 763         if len(args) < 1:
 764             raise UsageError, _('Not enough arguments supplied')
 765         classname = args[0]
 766
 767         # get the class
 768         cl = self.get_class(classname)
 769
 770         # figure the property names to display
 771         if len(args) > 1:
 772             prop_names = args[1].split(',')
 773             all_props = cl.getprops()
 774             for spec in prop_names:
 775                 if ':' in spec:
 776                     try:
 777                         propname, width = spec.split(':')
 778                     except (ValueError, TypeError):
 779                         raise UsageError, _('"%(spec)s" not name:width')%locals()
 780                 else:
 781                     propname = spec
 782                 if not all_props.has_key(propname):
 783                     raise UsageError, _('%(classname)s has no property '
 784                         '"%(propname)s"')%locals()
 785         else:
 786             prop_names = cl.getprops().keys()
 787
 788         # now figure column widths
 789         props = []
 790         for spec in prop_names:
 791             if ':' in spec:
 792                 name, width = spec.split(':')
 793                 props.append((name, int(width)))
 794             else:
 795                 props.append((spec, len(spec)))
 796
 797         # now display the heading
 798         print ' '.join([name.capitalize().ljust(width) for name,width in props])
 799
 800         # and the table data
 801         for nodeid in cl.list():
 802             l = []
 803             for name, width in props:
 804                 if name != 'id':
 805                     try:
 806                         value = str(cl.get(nodeid, name))
 807                     except KeyError:
 808                         # we already checked if the property is valid - a
 809                         # KeyError here means the node just doesn't have a
 810                         # value for it
 811                         value = ''
 812                 else:
 813                     value = str(nodeid)
 814                 f = '%%-%ds'%width
 815                 l.append(f%value[:width])
 816             print ' '.join(l)
 817         return 0
 818
 819     def do_history(self, args):
 820         '''Usage: history designator
 821         Show the history entries of a designator.
 822
 823         Lists the journal entries for the node identified by the designator.
 824         '''
 825         if len(args) < 1:
 826             raise UsageError, _('Not enough arguments supplied')
 827         try:
 828             classname, nodeid = hyperdb.splitDesignator(args[0])
 829         except hyperdb.DesignatorError, message:
 830             raise UsageError, message
 831
 832         try:
 833             print self.db.getclass(classname).history(nodeid)
 834         except KeyError:
 835             raise UsageError, _('no such class "%(classname)s"')%locals()
 836         except IndexError:
 837             raise UsageError, _('no such %(classname)s node "%(nodeid)s"')%locals()
 838         return 0
 839
 840     def do_commit(self, args):
 841         '''Usage: commit
 842         Commit all changes made to the database.
 843
 844         The changes made during an interactive session are not
 845         automatically written to the database - they must be committed
 846         using this command.
 847
 848         One-off commands on the command-line are automatically committed if
 849         they are successful.
 850         '''
 851         self.db.commit()
 852         return 0
 853
 854     def do_rollback(self, args):
 855         '''Usage: rollback
 856         Undo all changes that are pending commit to the database.
 857
 858         The changes made during an interactive session are not
 859         automatically written to the database - they must be committed
 860         manually. This command undoes all those changes, so a commit
 861         immediately after would make no changes to the database.
 862         '''
 863         self.db.rollback()
 864         return 0
 865
 866     def do_retire(self, args):
 867         '''Usage: retire designator[,designator]*
 868         Retire the node specified by designator.
 869
 870         This action indicates that a particular node is not to be retrieved by
 871         the list or find commands, and its key value may be re-used.
 872         '''
 873         if len(args) < 1:
 874             raise UsageError, _('Not enough arguments supplied')
 875         designators = args[0].split(',')
 876         for designator in designators:
 877             try:
 878                 classname, nodeid = hyperdb.splitDesignator(designator)
 879             except hyperdb.DesignatorError, message:
 880                 raise UsageError, message
 881             try:
 882                 self.db.getclass(classname).retire(nodeid)
 883             except KeyError:
 884                 raise UsageError, _('no such class "%(classname)s"')%locals()
 885             except IndexError:
 886                 raise UsageError, _('no such %(classname)s node "%(nodeid)s"')%locals()
 887         return 0
 888
 889     def do_export(self, args):
 890         '''Usage: export [class[,class]] export_dir
 891         Export the database to colon-separated-value files.
 892
 893         This action exports the current data from the database into
 894         colon-separated-value files that are placed in the nominated
 895         destination directory. The journals are not exported.
 896         '''
 897         # we need the CSV module
 898         if csv is None:
 899             raise UsageError, \
 900                 _('Sorry, you need the csv module to use this function.\n'
 901                 'Get it from: http://www.object-craft.com.au/projects/csv/')
 902
 903         # grab the directory to export to
 904         if len(args) < 1:
 905             raise UsageError, _('Not enough arguments supplied')
 906         dir = args[-1]
 907
 908         # get the list of classes to export
 909         if len(args) == 2:
 910             classes = args[0].split(',')
 911         else:
 912             classes = self.db.classes.keys()
 913
 914         # use the csv parser if we can - it's faster
 915         p = csv.parser(field_sep=':')
 916
 917         # do all the classes specified
 918         for classname in classes:
 919             cl = self.get_class(classname)
 920             f = open(os.path.join(dir, classname+'.csv'), 'w')
 921             properties = cl.getprops()
 922             propnames = properties.keys()
 923             propnames.sort()
 924             print >> f, p.join(propnames)
 925
 926             # all nodes for this class (not using list() 'cos it doesn't
 927             # include retired nodes)
 928
 929             for nodeid in self.db.getclass(classname).getnodeids():
 930                 # get the regular props
 931                 print >>f, p.join(cl.export_list(propnames, nodeid))
 932         return 0
 933
 934     def do_import(self, args):
 935         '''Usage: import import_dir
 936         Import a database from the directory containing CSV files, one per
 937         class to import.
 938
 939         The files must define the same properties as the class (including having
 940         a "header" line with those property names.)
 941
 942         The imported nodes will have the same nodeid as defined in the
 943         import file, thus replacing any existing content.
 944
 945         The new nodes are added to the existing database - if you want to
 946         create a new database using the imported data, then create a new
 947         database (or, tediously, retire all the old data.)
 948         '''
 949         if len(args) < 1:
 950             raise UsageError, _('Not enough arguments supplied')
 951         if csv is None:
 952             raise UsageError, \
 953                 _('Sorry, you need the csv module to use this function.\n'
 954                 'Get it from: http://www.object-craft.com.au/projects/csv/')
 955
 956         from roundup import hyperdb
 957
 958         for file in os.listdir(args[0]):
 959             f = open(os.path.join(args[0], file))
 960
 961             # get the classname
 962             classname = os.path.splitext(file)[0]
 963
 964             # ensure that the properties and the CSV file headings match
 965             cl = self.get_class(classname)
 966             p = csv.parser(field_sep=':')
 967             file_props = p.parse(f.readline())
 968             properties = cl.getprops()
 969             propnames = properties.keys()
 970             propnames.sort()
 971             m = file_props[:]
 972             m.sort()
 973             if m != propnames:
 974                 raise UsageError, _('Import file doesn\'t define the same '
 975                     'properties as "%(arg0)s".')%{'arg0': args[0]}
 976
 977             # loop through the file and create a node for each entry
 978             maxid = 1
 979             while 1:
 980                 line = f.readline()
 981                 if not line: break
 982
 983                 # parse lines until we get a complete entry
 984                 while 1:
 985                     l = p.parse(line)
 986                     if l: break
 987                     line = f.readline()
 988                     if not line:
 989                         raise ValueError, "Unexpected EOF during CSV parse"
 990
 991                 # do the import and figure the current highest nodeid
 992                 maxid = max(maxid, int(cl.import_list(propnames, l)))
 993
 994             print 'setting', classname, maxid+1
 995             self.db.setid(classname, str(maxid+1))
 996         return 0
 997
 998     def do_pack(self, args):
 999         '''Usage: pack period | date
1000
1001 Remove journal entries older than a period of time specified or
1002 before a certain date.
1003
1004 A period is specified using the suffixes "y", "m", and "d". The
1005 suffix "w" (for "week") means 7 days.
1006
1007       "3y" means three years
1008       "2y 1m" means two years and one month
1009       "1m 25d" means one month and 25 days
1010       "2w 3d" means two weeks and three days
1011
1012 Date format is "YYYY-MM-DD" eg:
1013     2001-01-01
1014
1015         '''
1016         if len(args) <> 1:
1017             raise UsageError, _('Not enough arguments supplied')
1018
1019         # are we dealing with a period or a date
1020         value = args[0]
1021         date_re = re.compile(r'''
1022               (?P<date>\d\d\d\d-\d\d?-\d\d?)? # yyyy-mm-dd
1023               (?P<period>(\d+y\s*)?(\d+m\s*)?(\d+d\s*)?)?
1024               ''', re.VERBOSE)
1025         m = date_re.match(value)
1026         if not m:
1027             raise ValueError, _('Invalid format')
1028         m = m.groupdict()
1029         if m['period']:
1030             pack_before = date.Date(". - %s"%value)
1031         elif m['date']:
1032             pack_before = date.Date(value)
1033         self.db.pack(pack_before)
1034         return 0
1035
1036     def do_reindex(self, args):
1037         '''Usage: reindex
1038         Re-generate a tracker's search indexes.
1039
1040         This will re-generate the search indexes for a tracker. This will
1041         typically happen automatically.
1042         '''
1043         self.db.indexer.force_reindex()
1044         self.db.reindex()
1045         return 0
1046
1047     def do_security(self, args):
1048         '''Usage: security [Role name]
1049         Display the Permissions available to one or all Roles.
1050         '''
1051         if len(args) == 1:
1052             role = args[0]
1053             try:
1054                 roles = [(args[0], self.db.security.role[args[0]])]
1055             except KeyError:
1056                 print _('No such Role "%(role)s"')%locals()
1057                 return 1
1058         else:
1059             roles = self.db.security.role.items()
1060             role = self.db.config.NEW_WEB_USER_ROLES
1061             if ',' in role:
1062                 print _('New Web users get the Roles "%(role)s"')%locals()
1063             else:
1064                 print _('New Web users get the Role "%(role)s"')%locals()
1065             role = self.db.config.NEW_EMAIL_USER_ROLES
1066             if ',' in role:
1067                 print _('New Email users get the Roles "%(role)s"')%locals()
1068             else:
1069                 print _('New Email users get the Role "%(role)s"')%locals()
1070         roles.sort()
1071         for rolename, role in roles:
1072             print _('Role "%(name)s":')%role.__dict__
1073             for permission in role.permissions:
1074                 if permission.klass:
1075                     print _(' %(description)s (%(name)s for "%(klass)s" '
1076                         'only)')%permission.__dict__
1077                 else:
1078                     print _(' %(description)s (%(name)s)')%permission.__dict__
1079         return 0
1080
1081     def run_command(self, args):
1082         '''Run a single command
1083         '''
1084         command = args[0]
1085
1086         # handle help now
1087         if command == 'help':
1088             if len(args)>1:
1089                 self.do_help(args[1:])
1090                 return 0
1091             self.do_help(['help'])
1092             return 0
1093         if command == 'morehelp':
1094             self.do_help(['help'])
1095             self.help_commands()
1096             self.help_all()
1097             return 0
1098
1099         # figure what the command is
1100         try:
1101             functions = self.commands.get(command)
1102         except KeyError:
1103             # not a valid command
1104             print _('Unknown command "%(command)s" ("help commands" for a '
1105                 'list)')%locals()
1106             return 1
1107
1108         # check for multiple matches
1109         if len(functions) > 1:
1110             print _('Multiple commands match "%(command)s": %(list)s')%{'command':
1111                 command, 'list': ', '.join([i[0] for i in functions])}
1112             return 1
1113         command, function = functions[0]
1114
1115         # make sure we have a tracker_home
1116         while not self.tracker_home:
1117             self.tracker_home = raw_input(_('Enter tracker home: ')).strip()
1118
1119         # before we open the db, we may be doing an install or init
1120         if command == 'initialise':
1121             try:
1122                 return self.do_initialise(self.tracker_home, args)
1123             except UsageError, message:
1124                 print _('Error: %(message)s')%locals()
1125                 return 1
1126         elif command == 'install':
1127             try:
1128                 return self.do_install(self.tracker_home, args)
1129             except UsageError, message:
1130                 print _('Error: %(message)s')%locals()
1131                 return 1
1132
1133         # get the tracker
1134         try:
1135             tracker = roundup.instance.open(self.tracker_home)
1136         except ValueError, message:
1137             self.tracker_home = ''
1138             print _("Error: Couldn't open tracker: %(message)s")%locals()
1139             return 1
1140
1141         # only open the database once!
1142         if not self.db:
1143             self.db = tracker.open('admin')
1144
1145         # do the command
1146         ret = 0
1147         try:
1148             ret = function(args[1:])
1149         except UsageError, message:
1150             print _('Error: %(message)s')%locals()
1151             print
1152             print function.__doc__
1153             ret = 1
1154         except:
1155             import traceback
1156             traceback.print_exc()
1157             ret = 1
1158         return ret
1159
1160     def interactive(self):
1161         '''Run in an interactive mode
1162         '''
1163         print _('Roundup %s ready for input.'%roundup_version)
1164         print _('Type "help" for help.')
1165         try:
1166             import readline
1167         except ImportError:
1168             print _('Note: command history and editing not available')
1169
1170         while 1:
1171             try:
1172                 command = raw_input(_('roundup> '))
1173             except EOFError:
1174                 print _('exit...')
1175                 break
1176             if not command: continue
1177             args = token.token_split(command)
1178             if not args: continue
1179             if args[0] in ('quit', 'exit'): break
1180             self.run_command(args)
1181
1182         # exit.. check for transactions
1183         if self.db and self.db.transactions:
1184             commit = raw_input(_('There are unsaved changes. Commit them (y/N)? '))
1185             if commit and commit[0].lower() == 'y':
1186                 self.db.commit()
1187         return 0
1188
1189     def main(self):
1190         try:
1191             opts, args = getopt.getopt(sys.argv[1:], 'i:u:hc')
1192         except getopt.GetoptError, e:
1193             self.usage(str(e))
1194             return 1
1195
1196         # handle command-line args
1197         self.tracker_home = os.environ.get('TRACKER_HOME', '')
1198         # TODO: reinstate the user/password stuff (-u arg too)
1199         name = password = ''
1200         if os.environ.has_key('ROUNDUP_LOGIN'):
1201             l = os.environ['ROUNDUP_LOGIN'].split(':')
1202             name = l[0]
1203             if len(l) > 1:
1204                 password = l[1]
1205         self.comma_sep = 0
1206         for opt, arg in opts:
1207             if opt == '-h':
1208                 self.usage()
1209                 return 0
1210             if opt == '-i':
1211                 self.tracker_home = arg
1212             if opt == '-c':
1213                 self.comma_sep = 1
1214
1215         # if no command - go interactive
1216         # wrap in a try/finally so we always close off the db
1217         ret = 0
1218         try:
1219             if not args:
1220                 self.interactive()
1221             else:
1222                 ret = self.run_command(args)
1223                 if self.db: self.db.commit()
1224             return ret
1225         finally:
1226             if self.db:
1227                 self.db.close()
1228
1229 if __name__ == '__main__':
1230     tool = AdminTool()
1231     sys.exit(tool.main())
1232
1233 # vim: set filetype=python ts=4 sw=4 et si