]> git.saurik.com Git - wxWidgets.git/blob - wxPython/wx/tools/dbg.py
reSWIGged
[wxWidgets.git] / wxPython / wx / tools / dbg.py
1 #----------------------------------------------------------------------------
2 # Name: dbg.py
3 # RCS-ID: $Id$
4 # Author: Will Sadkin
5 # Email: wsadkin@nameconnector.com
6 # Created: 07/11/2002
7 # Copyright: (c) 2002 by Will Sadkin, 2002
8 # License: wxWindows license
9 #----------------------------------------------------------------------------
10 # 12/21/2003 - Jeff Grimmett (grimmtooth@softhome.net)
11 #
12 # o V2.5 compatability update
13 #
14
15 """
16 This module provides a useful debugging framework that supports
17 showing nesting of function calls and allows a program to contain
18 lots of debugging print statements that can easily be turned on
19 or off to debug the code. It also supports the ability to
20 have each function indent the debugging statements contained
21 within it, including those of any other function called within
22 its scope, thus allowing you to see in what order functions are
23 being called, and from where.
24
25 This capability is particularly useful in wxPython applications,
26 where exactly events occur that cause functions to be called is
27 not entirely clear, and because wxPython programs can't be run
28 from inside other debugging environments that have their own
29 message loops.
30
31 This module defines a Logger class, responsible for managing
32 debugging output. Each Logger instance can be given a name
33 at construction; if this is done, '<name>:' will precede each
34 logging output made by that Logger instance.
35
36 The log() function this class provides takes a set of positional
37 arguments that are printed in order if debugging is enabled
38 (just like print does), followed by a set of keyword arguments
39 that control the behavior of the log() function itself on subsequent
40 calls. The current keyword arguments are:
41
42 indent
43 When set to a value of 1, this increments the current
44 indentation level, causing all subsequent dbg() outputs to be
45 indented by 3 more spaces. When set to a value of 0,
46 this process is reversed, causing the indent to decrease by
47 3 spaces. The default indentation level is 0.
48
49 enable
50 When set to a value of 1, this turns on dbg() output for
51 for program importing this module, until told to do otherwise.
52 When set to a value of 0, dbg output is turned off. (dbg
53 output is off by default.)
54
55 suspend
56 When set to a value of 1, this increments the current
57 "suspension" level. This makes it possible for a function
58 to temporarily suspend its and any of its dependents'
59 potential outputs that use the same Logger instance.
60 When set to a value of 0, the suspension level is
61 decremented. When the value goes back to 0, potential
62 logging is resumed (actual output depends on the
63 "enable" status of the Logger instance in question.)
64
65 wxlog
66 When set to a value of 1, the output will be sent to the
67 active wxLog target.
68
69 stream
70 When set to a non-None value, the current output stream
71 (default of sys.stdout) is pushed onto a stack of streams,
72 and is replaced in the dbg system with the specified stream.
73 When called with a value of None, the previous stream will
74 be restored (if stacked.) If set to None without previously
75 changing it will result in no action being taken.
76
77 You can also call the log function implicitly on the Logger
78 instance, ie. you can type:
79 from wxPython.tools.dbg import Logger
80 dbg = Logger()
81 dbg('something to print')
82
83 Using this fairly simple mechanism, it is possible to get fairly
84 useful debugging output in a program. Consider the following
85 code example:
86
87 >>> d = {1:'a', 2:'dictionary', 3:'of', 4:'words'}
88 >>> dbg = dbg.Logger('module')
89 >>> dbg(enable=1)
90 module: dbg enabled
91 >>> def foo(d):
92 ... dbg('foo', indent=1)
93 ... bar(d)
94 ... dbg('end of foo', indent=0)
95 ...
96 >>> def bar(d):
97 ... dbg('bar', indent=1)
98 ... dbg('contents of d:', indent=1)
99 ... l = d.items()
100 ... l.sort()
101 ... for key, value in l:
102 ... dbg('%d =' % key, value)
103 ... dbg(indent=0)
104 ... dbg('end of bar', indent=0)
105 ...
106 >>> foo(d)
107 module: foo
108 module: bar
109 module: contents of d:
110 module: 1 = a
111 module: 2 = dictionary
112 module: 3 = of
113 module: 4 = words
114 module: end of bar
115 module: end of foo
116 >>>
117
118 """
119
120
121 class Logger:
122 def __init__(self, name=None):
123 import sys
124 self.name = name
125 self._indent = 0 # current number of indentations
126 self._dbg = 0 # enable/disable flag
127 self._suspend = 0 # allows code to "suspend/resume" potential dbg output
128 self._wxLog = 0 # use wxLogMessage for debug output
129 self._outstream = sys.stdout # default output stream
130 self._outstream_stack = [] # for restoration of streams as necessary
131
132
133 def IsEnabled():
134 return self._dbg
135
136 def IsSuspended():
137 return _suspend
138
139
140 def log(self, *args, **kwargs):
141 """
142 This function provides a useful framework for generating
143 optional debugging output that can be displayed at an
144 arbitrary level of indentation.
145 """
146 if not self._dbg and not 'enable' in kwargs.keys():
147 return
148
149 if self._dbg and len(args) and not self._suspend:
150 # (emulate print functionality)
151 strs = [str(arg) for arg in args]
152 output = ' '.join(strs)
153 if self.name: output = self.name+': ' + output
154 output = ' ' * 3 * self._indent + output
155
156 if self._wxLog:
157 from wxPython.wx import wxLogMessage # (if not already imported)
158 wxLogMessage(output)
159 else:
160 self._outstream.write(output + '\n')
161 self._outstream.flush()
162 # else do nothing
163
164 # post process args:
165 for kwarg, value in kwargs.items():
166 if kwarg == 'indent':
167 self.SetIndent(value)
168 elif kwarg == 'enable':
169 self.SetEnabled(value)
170 elif kwarg == 'suspend':
171 self.SetSuspend(value)
172 elif kwarg == 'wxlog':
173 self.SetWxLog(value)
174 elif kwarg == 'stream':
175 self.SetStream(value)
176
177 # aliases for the log function
178 dbg = log # backwards compatible
179 msg = log #
180 __call__ = log # this one lets you 'call' the instance directly
181
182
183 def SetEnabled(self, value):
184 if value:
185 old_dbg = self._dbg
186 self._dbg = 1
187 if not old_dbg:
188 self.dbg('dbg enabled')
189 else:
190 if self._dbg:
191 self.dbg('dbg disabled')
192 self._dbg = 0
193
194
195 def SetSuspend(self, value):
196 if value:
197 self._suspend += 1
198 elif self._suspend > 0:
199 self._suspend -= 1
200
201
202 def SetIndent(self, value):
203 if value:
204 self._indent += 1
205 elif self._indent > 0:
206 self._indent -= 1
207
208
209 def SetWxLog(self, value):
210 self._wxLog = value
211
212
213 def SetStream(self, value):
214 if value:
215 self._outstream_stack.append( self._outstream )
216 self._outstream = value
217 elif value is None and len(self._outstream_stack) > 0:
218 self._outstream = self._outstream_stack.pop(-1)
219
220
221 #------------------------------------------------------------
222
223 if __name__ == "__main__":
224 import sys
225 import wx
226
227 wx.Log_SetActiveTarget( wx.LogStderr() )
228 logger = Logger('module')
229 dbg = logger.dbg
230 dbg(enable=1)
231 logger('test __call__ interface')
232 dbg('testing wxLog output to stderr:', wxlog=1, indent=1)
233 dbg('1,2,3...')
234 dbg('testing wx.LogNull:')
235 devnull = wx.LogNull()
236 dbg('4,5,6...') # shouldn't print, according to doc...
237 del devnull
238 dbg('(resuming to wx.LogStdErr)', '7,8,9...', indent=0)
239 dbg('disabling wx.Log output, switching to stderr:')
240 dbg(wxlog=0, stream=sys.stderr)
241 dbg(logger._outstream, 'switching back to stdout:')
242 dbg(stream=None)
243 dbg(logger._outstream )
244 def foo(str):
245 dbg('foo:', indent=1)
246 dbg(str, indent=0)
247 foo('testing dbg inside function')
248 class bar(Logger):
249 def __init__(self, name):
250 Logger.__init__(self, name)
251 def enable(self, value):
252 self.dbg(enable=value)
253 def foo(self, str):
254 self.dbg('foo:', indent=1)
255 self.dbg(str, indent=0)
256 f = bar('class mixin')
257 f.foo("shouldn't print")
258 f.enable(1)
259 f.foo("should print")
260 dbg('test completed.', enable=0)
261 dbg('(double-checking ;-)')
262