You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a gdb-like debugger for Python. It is a rewrite of *pdb* from
11
-
the ground up. It is both a high-level debugger as well as a
12
-
lower-level bytecode debugger. By lower-level debugger, I mean that it
13
-
understands a lot about byte code and will try to make use of that in
14
-
its normal higher-level instructions.
11
+
the ground up. I was disappointed with the flakiness,
12
+
imprecision, and poor quality of coding, modularity, and level of
13
+
documentation when I first looked at *pdb*.
15
14
16
-
A command-line interface (CLI) is provided as well as an remote access
15
+
``trepan3k`` is both a high-level debugger as well as a lower-level
16
+
bytecode debugger inspector. The code understands a lot about byte
17
+
code and the Python code object. The debugger makes use of this
18
+
knowledge to get more precise and accurate results and provide more
19
+
reliable operations.
20
+
21
+
A command-line interface (CLI) is provided as well as remote access
17
22
interface over TCP/IP.
18
23
19
-
See the Tutorial_ for how to use. See ipython-trepan_ for using this
20
-
in *ipython* or an *ipython notebook*.
24
+
See the entry_exit_ for the various ways you can enter the debugger.
21
25
22
-
This package is for Python 3.2 and above. See trepan2_ for the same code
23
-
modified to work with Python 2.
26
+
This code supports versions of Python back to version 3.0 using
27
+
different *git* branches. See trepan2_ for the same code modified to
28
+
work with Python 2.
24
29
25
30
Features
26
31
========
@@ -30,25 +35,36 @@ in general, knowledge gained by learning this is transferable to those
30
35
debuggers and vice versa.
31
36
32
37
There's a lot of cool stuff here that's not in the stock
33
-
Python debugger *pdb*, or in any other Python debugger that I know about.
38
+
Python debugger *pdb*, or any other Python debugger that I know about.
34
39
35
40
36
41
More Exact location information
37
42
-------------------------------
38
43
39
-
Python reports line information on the granularity of a line. To get
40
-
more precise information, we can (de)parse into Python the byte code
41
-
around a bytecode offset such as the place you are stopped at.
44
+
Python reports line information on the granularity of a line. For
45
+
Python versions up to 3.8, To get more precise information, we can
46
+
(de)parse into Python the byte code around a bytecode offset such as
47
+
the place you are stopped at.
48
+
49
+
So far as I know, there is no other debugger that decompiles code at
50
+
runtime to narrow position down to the specific bytecode
51
+
instruction.
42
52
43
-
So far as I know, there is no other debugger that decompile code at runtime.
53
+
See the deparse_ command for details on getting this kind of
54
+
information.
44
55
45
-
See the deparse_ command for details.
56
+
The problem with deparsing after 3.8 is that there is no decompiler
57
+
that can deparse code and give associations to bytecode
58
+
instructions. I am slowly working on that though.
46
59
47
-
We use information in the line number table in byte to understand
48
-
which lines are breakpointable, and in which module or function the
49
-
line appears in. Use info_line_ to see this information.
60
+
We use information in Python's code object line number table in byte
61
+
to understand which lines are breakpointable, and in which module or
62
+
function the line appears in. Use info_line_ to see this
63
+
information. Most if not all other debuggers do go to such lengths,
64
+
and as a result, it is possible to request stopping on a line number
65
+
that can never occur without complaint.
50
66
51
-
In the future we may allow specifiying an offset to indicate which
67
+
In the future, we may allow specifying an offset to indicate which
52
68
offset to stop at when there are several choices for a given line
53
69
number.
54
70
@@ -57,17 +73,17 @@ Debugging Python bytecode (no source available)
57
73
-----------------------------------------------
58
74
59
75
You can pass the debugger the name of Python bytecode and many times,
60
-
the debugger will merrily proceed. This debugger tries very hard find
61
-
the source code. Either by using the current executable search path
62
-
(e.g. ``PATH``) or for some by looking inside the bytecode for a
76
+
the debugger will merrily proceed. This debugger tries very hard to
77
+
find the source code. Either by using the current executable search
78
+
path (e.g. ``PATH``) or for some by looking inside the bytecode for a
63
79
filename in the main code object (``co_filename``) and applying that
64
-
with a search path which takes into account directory where the
80
+
with a search path that takes into account the directory where the
65
81
bytecode lives.
66
82
67
83
Failing to find source code this way, and in other situations where
68
84
source code can't be found, the debugger will decompile the bytecode
69
-
and use that for showing source test. *This allows us to debug `eval`'d
70
-
or `exec''d code.*
85
+
and use that for showing the source text. *This allows us to debug ``eval``'d
86
+
or ``exec``'d code.*
71
87
72
88
But if you happen to know where the source code is located, you can
73
89
associate a file source code with the current name listed in the
@@ -76,7 +92,7 @@ bytecode. See the set_substitute_ command for details here.
76
92
Source-code Syntax Colorization
77
93
-------------------------------
78
94
79
-
Terminal source code is colorized via pygments_. And with that you
95
+
Terminal source code is colorized via pygments_. And with that, you
80
96
can set the pygments color style, e.g. "colorful", "paraiso-dark". See
81
97
set_style_ . Furthermore, we make use of terminal bold and emphasized
82
98
text in debugger output and help text. Of course, you can also turn
@@ -89,24 +105,28 @@ we support that too in both dark and light themes.
89
105
Command Completion
90
106
------------------
91
107
92
-
GNU readline command completion is available. Command completion is
93
-
not just a simple static list, but varies depending on the
94
-
context. For example, for frame-changing commands which take optional
95
-
numbers, on the list of *valid numbers* is considered.
108
+
Command completion is available for GNU readline and
109
+
``prompt_toolkit``. While prompt_toolkit is new, command completion for
110
+
GNU Readline is not just a simple static list but varies depending on
111
+
the context. For example, for frame-changing commands that take
112
+
optional numbers, the list of *valid numbers* is considered.
113
+
114
+
In time (and perhaps with some volunteers), ``prompt_toolkit``
115
+
completion will be as good as GNU Readline completion.
96
116
97
117
Terminal Handling
98
118
-----------------
99
119
100
120
We can adjust debugger output depending on the line width of your
101
-
terminal. If it changes, or you want to adjust it, see set_width_.
121
+
terminal. If it changes, or you want to adjust it, see set_width_.
102
122
103
123
Smart Eval
104
124
----------
105
125
106
126
If you want to evaluate the current source line before it is run in
107
-
the code, use ``eval``. To evaluate text of a common fragment of line,
108
-
such as the expression part of an *if* statement, you can do that with
109
-
``eval?``. See eval_ for more information.
127
+
the code, use ``eval``. To evaluate the text of a common fragment of a
128
+
line, such as the expression part of an *if* statement, you can do
129
+
that with ``eval?``. See eval_ for more information.
110
130
111
131
Function Breakpoints
112
132
---------------------
@@ -117,8 +137,8 @@ are fundamentally different. If I write::
117
137
118
138
def five(): return 5
119
139
120
-
this line means has three different kinds of things. First there is
121
-
the code in Python that defines function ``five()`` for the first
140
+
this line contains three different kinds of things. First, there is
141
+
the code in Python that defines the function ``five()`` for the first
122
142
time. Then there is the function itself, and then there is some code
123
143
inside that function.
124
144
@@ -135,26 +155,26 @@ Also ``five`` could be a method of an object that is currently defined when the
135
155
More Stepping Control
136
156
---------------------
137
157
138
-
Sometimes you want small steps, and sometimes large stepping.
158
+
Sometimes you want small steps, and sometimes large steps.
139
159
140
-
This fundamental issue is handled in a couple ways:
160
+
This fundamental issue is handled in a couple of ways:
141
161
142
162
Step Granularity
143
163
................
144
164
145
165
There are now ``step`` *event* and ``next`` *event* commands with
146
-
aliases to ``s+``, ``s>`` and so on. The plus-suffixed commands force
166
+
aliases to ``s+``, ``s>``, and so on. The plus-suffixed commands force
147
167
a different line on a subsequent stop, the dash-suffixed commands
148
168
don't. Suffixes ``>``, ``<``, and ``!`` specify ``call``, ``return``
149
-
and ``exception`` events respectively. And without a suffix you get
169
+
and ``exception`` events respectively. And without a suffix, you get
150
170
the default; this is set by the ``set different`` command.
151
171
152
172
Event Filtering and Tracing
153
173
...........................
154
174
155
-
By default the debugger stops at every event: ``call``, ``return``,
175
+
By default, the debugger stops at every event: ``call``, ``return``,
156
176
``line``, ``exception``, ``c-call``, ``c-exception``. If you just want
157
-
to stop at ``line`` events (which is largely what you happens in
177
+
to stop at ``line`` events (which is largely what happens in
158
178
*pdb*) you can. If however you just want to stop at calls and returns,
159
179
that's possible too. Or pick some combination.
160
180
@@ -165,37 +185,36 @@ Event Tracing of Calls and Returns
165
185
166
186
I'm not sure why this was not done before. Probably because of the
167
187
lack of the ability to set and move by different granularities,
168
-
tracing calls and returns lead to too many uninteresting stops (such
188
+
tracing calls and returns leads to too many uninteresting stops (such
169
189
as at the same place you just were at). Also, stopping on function
170
190
definitions probably also added to this tedium.
171
191
172
-
Because we're really handling return events, we can show you the return value. (*pdb* has an "undocumented" *retval* command that doesn't seem to work.)
192
+
Because we're really handling return events, we can stop on the
193
+
return. This is a little more precise than *pdb*'s *retval* command.
173
194
174
195
Debugger Macros via Python Lambda expressions
175
196
---------------------------------------------
176
197
177
198
There are debugger macros. In *gdb*, there is a *macro* debugger
178
199
command to extend debugger commands.
179
200
180
-
However Python has its own rich programming language so it seems silly
201
+
However, Python has its own rich programming language so it seems silly
181
202
to recreate the macro language that is in *gdb*. Simpler and more
182
203
powerful is just to use Python here. A debugger macro here is just a
183
-
lambda expression which returns a string or a list of strings. Each
204
+
lambda expression that returns a string or a list of strings. Each
184
205
string returned should be a debugger command.
185
206
186
207
We also have *aliases* for the extremely simple situation where you
187
208
want to give an alias to an existing debugger command. But beware:
188
-
some commands, like step_ inspect command suffixes and change their
209
+
Some commands, like step_ inspect command suffixes and change their
189
210
behavior accordingly.
190
211
191
-
We also envision a number of other ways to allow extension of this
192
-
debugger either through additional modules, or user-supplied debugger
193
-
command directories.
212
+
We also provide extending the debugger either through additional Python packages.
194
213
195
214
Byte-code Instruction Introspection
196
215
------------------------------------
197
216
198
-
We do more in the way of looking at the byte codes to give better information. Through this we can provide:
217
+
We do more in the way of looking at the byte codes to give better information. Through this, we can provide:
199
218
200
219
* a *skip* command. It is like the *jump* command, but you don't have
201
220
to deal with line numbers.
@@ -206,7 +225,7 @@ We do more in the way of looking at the byte codes to give better information. T
206
225
misfeature.)
207
226
* Check that breakpoints are set only where they make sense.
208
227
* A more accurate determination of if you are at a function-defining
209
-
*def* or *class* statements (because the caller instruction contains
228
+
*def* or *class* statements (because the caller's instruction contains
210
229
``MAKE_FUNCTION`` or ``BUILD_CLASS``.)
211
230
212
231
Even without "deparsing" mentioned above, the ability to disassemble
@@ -219,7 +238,7 @@ Some Debugger Command Arguments can be Variables and Expressions
219
238
220
239
Commands that take integer arguments like *up*, *list*, or
221
240
*disassemble* allow you to use a Python expression which may include
222
-
local or global variables that evaluates to an integer. This
241
+
local or global variables that evaluate to an integer. This
223
242
eliminates the need in *gdb* for special "dollar" debugger
224
243
variables. (Note however because of *shlex* parsing, expressions can't
225
244
have embedded blanks.)
@@ -229,8 +248,8 @@ Out-of-Process Debugging
229
248
230
249
You can now debug your program in a different process or even a different computer on a different network!
231
250
232
-
Related, is flexible support for remapping path names from file
233
-
system, e.g. that inside a docker container or on a remote filesystem
251
+
Related, is flexible support for remapping path names from the file
252
+
system, e.g. the filesystem seen inside a docker container or on a remote filesystem
234
253
with locally-installed files. See subst_ for more information.
235
254
236
255
Egg, Wheel, and Tarballs
@@ -239,22 +258,28 @@ Egg, Wheel, and Tarballs
239
258
Can be installed via the usual *pip* or *easy_install*. There is a
240
259
source tarball. `How To Install
241
260
<https://python3-trepan.readthedocs.io/en/latest/install.html>`_ has
242
-
full instructions and installing from git and by other means.
261
+
full instructions and installation using *git* or by other means.
243
262
244
263
Modularity
245
264
----------
246
265
247
-
The Debugger plays nice with other trace hooks. You can have several debugger objects.
266
+
Because this debugger is modular, I have been able to use it as the basis
267
+
for debuggers in other projects. In particular, it is used as a module in trepanxpy_, a debugger for Python interpreter, x-python_, written in Python.
248
268
249
-
Many of the things listed below doesn't directly effect end-users, but
269
+
It is also used as a module inside an experimental open-source Wolfram Mathematica interpreter, Mathics3_.
270
+
271
+
Using pytracer_, the Debugger plays nice with other trace hooks. You
272
+
can have several debugger objects.
273
+
274
+
Many of the things listed below do not directly impact end-users, but
250
275
it does eventually by way of more robust and featureful code. And
251
276
keeping developers happy is a good thing.(TM)
252
277
253
-
* Commands and subcommands are individual classes now, not methods in a class. This means they now have properties like the context in which they can be run, minimum abbreviation name or alias names. To add a new command you basically add a file in a directory.
254
-
* I/O is it's own layer. This simplifies interactive readline behavior from reading commands over a TCP socket.
255
-
* An interface is it's own layer. Local debugging, remote debugging, running debugger commands from a file (``source``) are different interfaces. This means, for example, that we are able to give better error reporting if a debugger command file has an error.
278
+
* Commands and subcommands are individual classes now, not methods in a class. This means they now have properties like the context in which they can be run, minimum abbreviation names, or alias names. To add a new command you basically add a file in a directory.
279
+
* I/O is its own layer. This simplifies interactive readline behavior from reading commands over a TCP socket.
280
+
* An interface is its own layer. Local debugging, remote debugging, and running debugger commands from a file (``source``) are different interfaces. This means, for example, that we are able to give better error reporting if a debugger command file has an error.
256
281
* There is an experimental Python-friendly interface for front-ends
257
-
* more testable. Much more unit and functional tests. More of *pydb*'s integration test will eventually be added.
282
+
* more testable. Much more unit and functional tests.
0 commit comments