xmpp.debug

1 ## debug.py 2 ## 3 ## Copyright (C) 2003 Jacob Lundqvist 4 ## 5 ## This program is free software; you can redistribute it and/or modify 6 ## it under the terms of the GNU Lesser General Public License as published 7 ## by the Free Software Foundation; either version 2, or (at your option) 8 ## any later version. 9 ## 10 ## This program is distributed in the hope that it will be useful, 11 ## but WITHOUT ANY WARRANTY; without even the implied warranty of 12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 ## GNU Lesser General Public License for more details. 14 15 _version_ = '1.4.0' 16 17 """\ 18 19 Generic debug class 20 21 Other modules can always define extra debug flags for local usage, as long as 22 they make sure they append them to debug_flags 23 24 Also its always a good thing to prefix local flags with something, to reduce risk 25 of coliding flags. Nothing breaks if two flags would be identical, but it might 26 activate unintended debugging. 27 28 flags can be numeric, but that makes analysing harder, on creation its 29 not obvious what is activated, and when flag_show is given, output isnt 30 really meaningfull. 31 32 This Debug class can either be initialized and used on app level, or used independantly 33 by the individual classes. 34 35 For samples of usage, see samples subdir in distro source, and selftest 36 in this code 37 38 """ 39 40 41 42 import sys 43 import traceback 44 import time 45 import os 46 47 import types 48 49 if os.environ.has_key('TERM'): 50 colors_enabled=True 51 else: 52 colors_enabled=False 53 54 color_none = chr(27) + "[0m" 55 color_black = chr(27) + "[30m" 56 color_red = chr(27) + "[31m" 57 color_green = chr(27) + "[32m" 58 color_brown = chr(27) + "[33m" 59 color_blue = chr(27) + "[34m" 60 color_magenta = chr(27) + "[35m" 61 color_cyan = chr(27) + "[36m" 62 color_light_gray = chr(27) + "[37m" 63 color_dark_gray = chr(27) + "[30;1m" 64 color_bright_red = chr(27) + "[31;1m" 65 color_bright_green = chr(27) + "[32;1m" 66 color_yellow = chr(27) + "[33;1m" 67 color_bright_blue = chr(27) + "[34;1m" 68 color_purple = chr(27) + "[35;1m" 69 color_bright_cyan = chr(27) + "[36;1m" 70 color_white = chr(27) + "[37;1m" 71 72 73 """ 74 Define your flags in yor modules like this: 75 76 from debug import * 77 78 DBG_INIT = 'init' ; debug_flags.append( DBG_INIT ) 79 DBG_CONNECTION = 'connection' ; debug_flags.append( DBG_CONNECTION ) 80 81 The reason for having a double statement wis so we can validate params 82 and catch all undefined debug flags 83 84 This gives us control over all used flags, and makes it easier to allow 85 global debugging in your code, just do something like 86 87 foo = Debug( debug_flags ) 88 89 group flags, that is a flag in it self containing multiple flags should be 90 defined without the debug_flags.append() sequence, since the parts are already 91 in the list, also they must of course be defined after the flags they depend on ;) 92 example: 93 94 DBG_MULTI = [ DBG_INIT, DBG_CONNECTION ] 95 96 97 98 NoDebug 99 ------- 100 To speed code up, typically for product releases or such 101 use this class instead if you globaly want to disable debugging 102 """ 103 104

105 -class NoDebug:

106 - def __init__( self, *args, **kwargs ):

107 self.debug_flags = []

108 - def show( self, *args, **kwargs):

109 pass

110 - def Show( self, *args, **kwargs):

111 pass

112 - def is_active( self, flag ):

113 pass

114 colors={}

115 - def active_set( self, active_flags = None ):

116 return 0

117 118 119 LINE_FEED = '\n' 120 121

122 -class Debug:

123 - def __init__( self, 124 # 125 # active_flags are those that will trigger output 126 # 127 active_flags = None, 128 # 129 # Log file should be file object or file namne 130 # 131 log_file = sys.stderr, 132 # 133 # prefix and sufix can either be set globaly or per call. 134 # personally I use this to color code debug statements 135 # with prefix = chr(27) + '[34m' 136 # sufix = chr(27) + '[37;1m\n' 137 # 138 prefix = 'DEBUG: ', 139 sufix = '\n', 140 # 141 # If you want unix style timestamps, 142 # 0 disables timestamps 143 # 1 before prefix, good when prefix is a string 144 # 2 after prefix, good when prefix is a color 145 # 146 time_stamp = 0, 147 # 148 # flag_show should normaly be of, but can be turned on to get a 149 # good view of what flags are actually used for calls, 150 # if it is not None, it should be a string 151 # flags for current call will be displayed 152 # with flag_show as separator 153 # recomended values vould be '-' or ':', but any string goes 154 # 155 flag_show = None, 156 # 157 # If you dont want to validate flags on each call to 158 # show(), set this to 0 159 # 160 validate_flags = 1, 161 # 162 # If you dont want the welcome message, set to 0 163 # default is to show welcome if any flags are active 164 welcome = -1 165 ):

166 167 self.debug_flags = [] 168 if welcome == -1: 169 if active_flags and len(active_flags): 170 welcome = 1 171 else: 172 welcome = 0 173 174 self._remove_dupe_flags() 175 if log_file: 176 if type( log_file ) is type(''): 177 try: 178 self._fh = open(log_file,'w') 179 except: 180 print 'ERROR: can open %s for writing' 181 sys.exit(0) 182 else: ## assume its a stream type object 183 self._fh = log_file 184 else: 185 self._fh = sys.stdout 186 187 if time_stamp not in (0,1,2): 188 msg2 = '%s' % time_stamp 189 raise 'Invalid time_stamp param', msg2 190 self.prefix = prefix 191 self.sufix = sufix 192 self.time_stamp = time_stamp 193 self.flag_show = None # must be initialised after possible welcome 194 self.validate_flags = validate_flags 195 196 self.active_set( active_flags ) 197 if welcome: 198 self.show('') 199 caller = sys._getframe(1) # used to get name of caller 200 try: 201 mod_name= ":%s" % caller.f_locals['__name__'] 202 except: 203 mod_name = "" 204 self.show('Debug created for %s%s' % (caller.f_code.co_filename, 205 mod_name )) 206 self.show(' flags defined: %s' % ','.join( self.active )) 207 208 if type(flag_show) in (type(''), type(None)): 209 self.flag_show = flag_show 210 else: 211 msg2 = '%s' % type(flag_show ) 212 raise 'Invalid type for flag_show!', msg2

213 214 215 216 217

218 - def show( self, msg, flag = None, prefix = None, sufix = None, 219 lf = 0 ):

220 """ 221 flag can be of folowing types: 222 None - this msg will always be shown if any debugging is on 223 flag - will be shown if flag is active 224 (flag1,flag2,,,) - will be shown if any of the given flags 225 are active 226 227 if prefix / sufix are not given, default ones from init will be used 228 229 lf = -1 means strip linefeed if pressent 230 lf = 1 means add linefeed if not pressent 231 """ 232 233 if self.validate_flags: 234 self._validate_flag( flag ) 235 236 if not self.is_active(flag): 237 return 238 if prefix: 239 pre = prefix 240 else: 241 pre = self.prefix 242 if sufix: 243 suf = sufix 244 else: 245 suf = self.sufix 246 247 if self.time_stamp == 2: 248 output = '%s%s ' % ( pre, 249 time.strftime('%b %d %H:%M:%S', 250 time.localtime(time.time() )), 251 ) 252 elif self.time_stamp == 1: 253 output = '%s %s' % ( time.strftime('%b %d %H:%M:%S', 254 time.localtime(time.time() )), 255 pre, 256 ) 257 else: 258 output = pre 259 260 if self.flag_show: 261 if flag: 262 output = '%s%s%s' % ( output, flag, self.flag_show ) 263 else: 264 # this call uses the global default, 265 # dont print "None", just show the separator 266 output = '%s %s' % ( output, self.flag_show ) 267 268 output = '%s%s%s' % ( output, msg, suf ) 269 if lf: 270 # strip/add lf if needed 271 last_char = output[-1] 272 if lf == 1 and last_char != LINE_FEED: 273 output = output + LINE_FEED 274 elif lf == -1 and last_char == LINE_FEED: 275 output = output[:-1] 276 try: 277 self._fh.write( output ) 278 except: 279 # unicode strikes again ;) 280 s=u'' 281 for i in range(len(output)): 282 if ord(output[i]) < 128: 283 c = output[i] 284 else: 285 c = '?' 286 s=s+c 287 self._fh.write( '%s%s%s' % ( pre, s, suf )) 288 self._fh.flush()

289 290

291 - def is_active( self, flag ):

292 'If given flag(s) should generate output.' 293 294 # try to abort early to quicken code 295 if not self.active: 296 return 0 297 if not flag or flag in self.active: 298 return 1 299 else: 300 # check for multi flag type: 301 if type( flag ) in ( type(()), type([]) ): 302 for s in flag: 303 if s in self.active: 304 return 1 305 return 0

306 307

308 - def active_set( self, active_flags = None ):

309 "returns 1 if any flags where actually set, otherwise 0." 310 r = 0 311 ok_flags = [] 312 if not active_flags: 313 #no debuging at all 314 self.active = [] 315 elif type( active_flags ) in ( types.TupleType, types.ListType ): 316 flags = self._as_one_list( active_flags ) 317 for t in flags: 318 if t not in self.debug_flags: 319 sys.stderr.write('Invalid debugflag given: %s\n' % t ) 320 ok_flags.append( t ) 321 322 self.active = ok_flags 323 r = 1 324 else: 325 # assume comma string 326 try: 327 flags = active_flags.split(',') 328 except: 329 self.show( '***' ) 330 self.show( '*** Invalid debug param given: %s' % active_flags ) 331 self.show( '*** please correct your param!' ) 332 self.show( '*** due to this, full debuging is enabled' ) 333 self.active = self.debug_flags 334 335 for f in flags: 336 s = f.strip() 337 ok_flags.append( s ) 338 self.active = ok_flags 339 340 self._remove_dupe_flags() 341 return r

342

343 - def active_get( self ):

344 "returns currently active flags." 345 return self.active

346 347

348 - def _as_one_list( self, items ):

349 """ init param might contain nested lists, typically from group flags. 350 351 This code organises lst and remves dupes 352 """ 353 if type( items ) <> type( [] ) and type( items ) <> type( () ): 354 return [ items ] 355 r = [] 356 for l in items: 357 if type( l ) == type([]): 358 lst2 = self._as_one_list( l ) 359 for l2 in lst2: 360 self._append_unique_str(r, l2 ) 361 elif l == None: 362 continue 363 else: 364 self._append_unique_str(r, l ) 365 return r

366 367

368 - def _append_unique_str( self, lst, item ):

369 """filter out any dupes.""" 370 if type(item) <> type(''): 371 msg2 = '%s' % item 372 raise 'Invalid item type (should be string)',msg2 373 if item not in lst: 374 lst.append( item ) 375 return lst

376 377

378 - def _validate_flag( self, flags ):

379 'verify that flag is defined.' 380 if flags: 381 for f in self._as_one_list( flags ): 382 if not f in self.debug_flags: 383 msg2 = '%s' % f 384 raise 'Invalid debugflag given', msg2

385

386 - def _remove_dupe_flags( self ):

387 """ 388 if multiple instances of Debug is used in same app, 389 some flags might be created multiple time, filter out dupes 390 """ 391 unique_flags = [] 392 for f in self.debug_flags: 393 if f not in unique_flags: 394 unique_flags.append(f) 395 self.debug_flags = unique_flags

396 397 colors={}

398 - def Show(self, flag, msg, prefix=''):

399 msg=msg.replace('\r','\\r').replace('\n','\\n').replace('><','>\n <') 400 if not colors_enabled: pass 401 elif self.colors.has_key(prefix): msg=self.colors[prefix]+msg+color_none 402 else: msg=color_none+msg 403 if not colors_enabled: prefixcolor='' 404 elif self.colors.has_key(flag): prefixcolor=self.colors[flag] 405 else: prefixcolor=color_none 406 407 if prefix=='error': 408 _exception = sys.exc_info() 409 if _exception[0]: 410 msg=msg+'\n'+''.join(traceback.format_exception(_exception[0], _exception[1], _exception[2])).rstrip() 411 412 prefix= self.prefix+prefixcolor+(flag+' '*12)[:12]+' '+(prefix+' '*6)[:6] 413 self.show(msg, flag, prefix)

414

415 - def is_active( self, flag ):

416 if not self.active: return 0 417 if not flag or flag in self.active and DBG_ALWAYS not in self.active or flag not in self.active and DBG_ALWAYS in self.active : return 1 418 return 0

419 420 DBG_ALWAYS='always' 421 422 ##Uncomment this to effectively disable all debugging and all debugging overhead. 423 #Debug=NoDebug 424

Source Code for Module xmpp.debug