Package csb :: Package apps
[frames] | no frames]

Source Code for Package csb.apps

  1  """ 
  2  Root package for all executable CSB client programs. 
  3   
  4  Introduction 
  5  ============ 
  6   
  7  There are roughly three types of CSB apps: 
  8       
  9      1. protocols: client applications, which make use of the core library 
 10         to perform some action     
 11      2. wrappers: these provide python bindings for external programs 
 12      3. mixtures of (1) and (2). 
 13   
 14  The main design goal of this framework is to provide a way for writing 
 15  executable code with minimal effort, without the hassle of repeating yourself 
 16  over and over again. Creating a professional-grade CLI, validating and 
 17  consuming the command line arguments is therefore really straightforward. 
 18  On the other hand, one frequently feels the need to reuse some apps or their 
 19  components in other apps. For such reasons, a CSB L{Application} is just a 
 20  regular, importable python object, which never communicates directly with the 
 21  command line interface or calls sys.exit(). The app's associated L{AppRunner} 
 22  will take care of those things.       
 23   
 24  Getting Started 
 25  =============== 
 26   
 27  Follow these simple steps to write a new CSB app: 
 28   
 29      1. Create the app module in the C{csb.apps} package. 
 30       
 31      2. Create a main class and derive it from L{csb.apps.Application}. You need 
 32      to implement the L{csb.apps.Application.main()} abstract method - this is 
 33      the app's entry point. You have the L{csb.apps.Application.args} object at 
 34      your disposal. 
 35       
 36      3. Create an AppRunner class, derived from csb.apps.AppRunner. You need to 
 37      implement the following methods and properties: 
 38       
 39          - property L{csb.apps.AppRunner.target} -- just return YourApp's class 
 40          - method L{csb.apps.AppRunner.command_line()} -- make an instance of 
 41          L{csb.apps.ArgHandler}, define your command line parameters on that 
 42          instance and return it 
 43          - optionally, override L{csb.apps.AppRunner.initapp(args)} if you need 
 44          to customize the instantiation of the main app class, or to perform 
 45          additional checks on the parsed application C{args} and eventually call 
 46          C{YourApp.exit()}. Return an instance of your app at the end  
 47       
 48      4. Make it executable:: 
 49          if __name__ == '__main__': 
 50              MyAppRunner().run() 
 51       
 52  See L{csb.apps.helloworld} for a sample implementation.     
 53  """ 
 54   
 55  import os 
 56  import re 
 57  import sys 
 58  import argparse 
 59  import traceback 
 60   
 61  from abc import ABCMeta, abstractmethod, abstractproperty 
62 63 64 -class ExitCodes(object):
65 """ 66 Exit code constants. 67 """ 68 CLEAN = 0 69 USAGE_ERROR = 1 70 CRASH = 99
71
72 -class AppExit(Exception):
73 """ 74 Used to signal an immediate application exit condition (e.g. a fatal error), 75 that propagates down to the client, instead of forcing the interpreter to 76 close via C{sys.exit()}. 77 78 @param message: exit message 79 @type message: str 80 @param code: exit code (see L{ExitCodes} for common constants) 81 @type code: int 82 @param usage: ask the app runner to print also the app's usage line 83 @type usage: bool 84 """ 85
86 - def __init__(self, message='', code=0, usage=False):
87 88 self.message = message 89 self.code = code 90 self.usage = usage
91
92 -class Application(object):
93 """ 94 Base CSB application class. 95 96 @param args: an object containing the application arguments 97 @type args: argparse.Namespace 98 """ 99 __metaclass__ = ABCMeta 100 101 USAGE = '' 102 HELP = '' 103
104 - def __init__(self, args, log=sys.stdout):
105 106 self.__args = None 107 self._log = log 108 109 self.args = args
110 111 @property
112 - def args(self):
113 """ 114 The object containing application's arguments, as returned by the 115 command line parser. 116 """ 117 return self.__args
118 @args.setter
119 - def args(self, args):
120 self.__args = args
121 122 @abstractmethod
123 - def main(self):
124 """ 125 The main application hook. 126 """ 127 pass
128
129 - def log(self, message, ending='\n'):
130 """ 131 Write C{message} to the logging stream and flush it. 132 133 @param message: message 134 @type message: str 135 """ 136 137 self._log.write(message) 138 self._log.write(ending) 139 self._log.flush()
140 141 @staticmethod
142 - def exit(message, code=0, usage=False):
143 """ 144 Notify the app runner about an application exit. 145 146 @param message: exit message 147 @type message: str 148 @param code: exit code (see L{ExitCodes} for common constants) 149 @type code: int 150 @param usage: advise the client to show the usage line 151 @type usage: bool 152 153 @note: you re not supposed to use C{sys.exit()} for the same purpose. 154 It is L{AppRunner}'s responsibility to handle the real system 155 exit, if the application has been started as an executable. 156 Think about your app being executed by some Python client as a 157 regular Python class, imported from a module -- in that case you 158 only want to ask the client to terminate the app, not to kill 159 the whole interpreter. 160 """ 161 raise AppExit(message, code, usage)
162
163 -class AppRunner(object):
164 """ 165 A base abstract class for all application runners. Concrete sub-classes 166 must define their corresponding L{Application} using the L{self.target} 167 property and must customize the L{Application}'s command line parser using 168 L{self.command_line()}. 169 170 @param argv: the list of command line arguments passed to the program. By 171 default this is C{sys.argv}. 172 @type argv: tuple of str 173 """ 174 __metaclass__ = ABCMeta 175
176 - def __init__(self, argv=sys.argv):
177 178 self._module = argv[0] 179 self._program = os.path.basename(self.module) 180 self._args = argv[1:]
181 182 @property
183 - def module(self):
184 return self._module
185 186 @property
187 - def program(self):
188 return self._program
189 190 @property
191 - def args(self):
192 return self._args
193 194 @abstractproperty
195 - def target(self):
196 """ 197 Reference to the concrete L{Application} class to run. This is 198 an abstract property that couples the current C{AppRunner} to its 199 corresponding L{Application}. 200 201 @rtype: type (class reference) 202 """ 203 return Application
204 205 @abstractmethod
206 - def command_line(self):
207 """ 208 Command line factory: build a command line parser suitable for the 209 application. 210 This is a hook method that each concrete AppRunner must implement. 211 212 @return: a command line parser object which knows how to handle 213 C{sys.argv} in the context of the concrete application. See the 214 documentation of L{ArgHandler} for more info on how to define command 215 line arguments. 216 217 @rtype: L{ArgHandler} 218 """ 219 # null implementation (no cmd arguments): 220 return ArgHandler(self.program)
221
222 - def initapp(self, args):
223 """ 224 Hook method that controls the instantiation of the main app class. 225 If the application has a custom constructor, you can adjust the 226 app initialization by overriding this method. 227 228 @param args: an object containing the application arguments 229 @type args: argparse.Namespace 230 231 @return: the application instance 232 @rtype: L{Application} 233 """ 234 app = self.target 235 return app(args)
236
237 - def run(self):
238 """ 239 Get the L{self.command_line()} and run L{self.target}. Ensure clean 240 system exit. 241 """ 242 try: 243 app = self.target 244 cmd = self.command_line() 245 246 try: 247 assert issubclass(app, Application) 248 assert isinstance(cmd, ArgHandler) 249 250 args = cmd.parse(self.args) 251 app.USAGE = cmd.usage 252 app.HELP = cmd.help 253 254 self.initapp(args).main() 255 256 except AppExit as ae: 257 if ae.usage: 258 AppRunner.exit(ae.message, code=ae.code, usage=cmd.usage) 259 else: 260 AppRunner.exit(ae.message, code=ae.code) 261 262 except SystemExit as se: # this should never happen, but just in case 263 AppRunner.exit(se.message, code=se.code) 264 265 except Exception: 266 message = '{0} has crashed. Details: \n{1}'.format(self.program, traceback.format_exc()) 267 AppRunner.exit(message, code=ExitCodes.CRASH) 268 269 AppRunner.exit(code=ExitCodes.CLEAN)
270 271 @staticmethod
272 - def exit(message='', code=0, usage='', ending='\n'):
273 """ 274 Perform system exit. If the exit C{code} is 0, print all messages to 275 STDOUT, else write to STDERR. 276 277 @param message: message to print 278 @type message: str 279 @param code: application exit code 280 @type code: int 281 """ 282 283 ending = str(ending or '') 284 message = str(message or '') 285 stream = sys.stdout 286 287 if code > 0: 288 message = 'E#{0} {1}'.format(code, message) 289 stream = sys.stderr 290 291 if usage: 292 stream.write(usage.rstrip(ending)) 293 stream.write(ending) 294 if message: 295 stream.write(message) 296 stream.write(ending) 297 298 sys.exit(code)
299
300 -class ArgHandler(object):
301 """ 302 Command line argument handler. 303 304 @param program: (file)name of the program, usually sys.argv[0] 305 @type program: str 306 @param description: long description of the application, shown in help 307 pages. The usage line and the parameter lists are 308 generated automatically, so no need to put them here. 309 @type description: str 310 311 @note: a help argument (-h) is provided automatically. 312 """ 313 314 SHORT_PREFIX = '-' 315 LONG_PREFIX = '--' 316
317 - class Type(object):
318 319 POSITIONAL = 1 320 NAMED = 2
321
322 - def __init__(self, program, description=''):
323 324 self._argformat = re.compile('^[a-z][a-z0-9_-]*$', re.IGNORECASE) 325 self._optformat = re.compile('^[a-z0-9]$', re.IGNORECASE) 326 327 self._program = program 328 self._description = description 329 330 self._parser = argparse.ArgumentParser(prog=program, description=description)
331
332 - def _add(self, kind, name, shortname, *a, **k):
333 334 args = [] 335 kargs = dict(k) 336 337 if shortname is not None: 338 if not re.match(self._optformat, shortname): 339 raise ValueError('Invalid short option name: {0}.'.format(shortname)) 340 341 if kind == ArgHandler.Type.POSITIONAL: 342 args.append(shortname) 343 else: 344 args.append(ArgHandler.SHORT_PREFIX + shortname) 345 346 if name is not None or kind == ArgHandler.Type.POSITIONAL: 347 if not re.match(self._argformat, name): 348 raise ValueError('Malformed argument name: {0}.'.format(name)) 349 350 if kind == ArgHandler.Type.POSITIONAL: 351 args.append(name) 352 else: 353 args.append(ArgHandler.LONG_PREFIX + name) 354 355 assert len(args) in (1, 2) 356 args.extend(a) 357 358 self.parser.add_argument(*args, **kargs)
359
360 - def _format_help(self, help, default):
361 362 if not help: 363 help = '' 364 if default is not None: 365 help = '{0} (default={1})'.format(help, default) 366 367 return help
368
369 - def add_positional_argument(self, name, type, help, choices=None):
370 """ 371 Define a mandatory positional argument (an argument without a dash). 372 373 @param name: name of the argument (used in help only) 374 @type name: str 375 @param type: argument data type 376 @type type: type (type factory callable) 377 @param help: help text 378 @type help: str 379 @param choices: list of allowed argument values 380 @type choices: tuple 381 """ 382 self._add(ArgHandler.Type.POSITIONAL, name, None, 383 type=type, help=help, choices=choices)
384
385 - def add_array_argument(self, name, type, help, choices=None):
386 """ 387 Same as L{self.add_positional_argument()}, but allow unlimited number 388 of values to be specified on the command line. 389 390 @param name: name of the argument (used in help only) 391 @type name: str 392 @param type: argument data type 393 @type type: type (type factory callable) 394 @param help: help text 395 @type help: str 396 @param choices: list of allowed argument values 397 @type choices: tuple 398 """ 399 self._add(ArgHandler.Type.POSITIONAL, name, None, 400 type=type, help=help, choices=choices, nargs=argparse.ONE_OR_MORE)
401
402 - def add_boolean_option(self, name, shortname, help, default=False):
403 """ 404 Define an optional switch (a dashed argument with no value). 405 406 @param name: long name of the option (or None) 407 @type name: str, None 408 @param shortname: short (single character) name of the option (or None) 409 @type shortname:str, None 410 @param help: help text 411 @type help: str 412 @param default: default value, assigned when the option is omitted. 413 If the option is specified on the command line, the 414 inverse value is assigned 415 @type default: bool 416 """ 417 if not default: 418 default = False 419 help = self._format_help(help, default) 420 421 if default: 422 action = 'store_false' 423 else: 424 action = 'store_true' 425 426 self._add(ArgHandler.Type.NAMED, name, shortname, 427 help=help, action=action, default=bool(default))
428
429 - def add_scalar_option(self, name, shortname, type, help, default=None, choices=None, required=False):
430 """ 431 Define a scalar option (a dashed argument that accepts a single value). 432 433 @param name: long name of the option (or None) 434 @type name: str, None 435 @param shortname: short (single character) name of the option (or None) 436 @type shortname: str, None 437 @param type: argument data type 438 @type type: type (type factory callable) 439 @param help: help text 440 @type help: str 441 @param default: default value, assigned when the option is omitted 442 @param choices: list of allowed argument values 443 @type choices: tuple 444 @param required: make this option a named mandatory argument 445 @type required: bool 446 """ 447 help = self._format_help(help, default) 448 449 self._add(ArgHandler.Type.NAMED, name, shortname, 450 type=type, help=help, default=default, choices=choices, required=required)
451
452 - def add_array_option(self, name, shortname, type, help, default=None, choices=None, required=False):
453 """ 454 Define an array option (a dashed argument that may receive one 455 or multiple values on the command line, separated with spaces). 456 457 @param name: long name of the option (or None) 458 @type name: str, None 459 @param shortname: short (single character) name of the option (or None) 460 @type shortname: str, None 461 @param type: argument data type 462 @type type: type (type factory callable) 463 @param help: help text 464 @type help: str 465 @param choices: list of allowed argument values 466 @type choices: tuple 467 @param required: make this option a named mandatory argument 468 @type required: bool 469 """ 470 help = self._format_help(help, default) 471 472 self._add(ArgHandler.Type.NAMED, name, shortname, 473 nargs=argparse.ZERO_OR_MORE, type=type, help=help, default=default, 474 choices=choices, required=required)
475
476 - def parse(self, args):
477 """ 478 Parse the command line arguments. 479 480 @param args: the list of user-provided command line arguments -- 481 normally sys.argv[1:] 482 @type args: tuple of str 483 484 @return: an object initialized with the parsed arguments 485 @rtype: argparse.Namespace 486 """ 487 try: 488 return self.parser.parse_args(args) 489 except SystemExit as se: 490 if se.code > 0: 491 raise AppExit('Bad command line', ExitCodes.USAGE_ERROR) 492 else: 493 raise AppExit(code=ExitCodes.CLEAN)
494 495 @property
496 - def parser(self):
497 return self._parser
498 499 @property
500 - def usage(self):
501 return self.parser.format_usage()
502 503 @property
504 - def help(self):
505 return self.parser.format_help()
506