Package: trepan3k
AbstractFeaturesMore Exact location informationDebugging Python bytecode (no source available)Source-code Syntax ColorizationCommand CompletionTerminal HandlingSmart EvalFunction BreakpointsMore Stepping ControlStep GranularityEvent Filtering and TracingEvent Tracing of Calls and ReturnsDebugger Macros via Python Lambda expressionsByte-code Instruction IntrospectionSome Debugger Command Arguments can be Variables and ExpressionsOut-of-Process DebuggingEgg, Wheel, and TarballsModularityDocumentationSee AlsoAbstractThis is a gdb-like debugger for Python. It is a rewrite ofpdbfrom
the ground up. It is both a high-level debugger as well as a
lower-level bytecode debugger. By lower-level debugger, I mean that it
understands a lot about byte code and will try to make use of that in
its normal higher-level instructions.A command-line interface (CLI) is provided as well as an remote access
interface over TCP/IP.See theTutorialfor how to use. Seeipython-trepanfor using this
inipythonor anipython notebook.This package is for Python 3.2 and above. Seetrepan2for the same code
modified to work with Python 2.FeaturesSince this debugger is similar toothertrepanningdebuggersandgdbin general, knowledge gained by learning this is transferable to those
debuggers and vice versa.There’s a lot of cool stuff here that’s not in the stock
Python debuggerpdb, or in any other Python debugger that I know about.More Exact location informationPython reports line information on the granularity of a line. To get
more precise information, we can (de)parse into Python the byte code
around a bytecode offset such as the place you are stopped at.So far as I know, there is no other debugger that decompile code at runtime.See thedeparsecommand for details.We use information in the line number table in byte to understand
which lines are breakpointable, and in which module or function the
line appears in. Useinfo_lineto see this information.In the future we may allow specifiying an offset to indicate which
offset to stop at when there are several choices for a given line
number.Debugging Python bytecode (no source available)You can pass the debugger the name of Python bytecode and many times,
the debugger will merrily proceed.  This debugger tries very hard find
the source code. Either by using the current executable search path
(e.g.PATH) or for some by looking inside the bytecode for a
filename in the main code object (co_filename) and applying that
with a search path which takes into account directory where the
bytecode lives.Failing to find source code this way, and in other situations where
source code can’t be found, the debugger will decompile the bytecode
and use that for showing source test.This allows us to debug `eval`’d
or `exec’’d code.But if you happen to know where the source code is located, you can
associate a file source code with the current name listed in the
bytecode. See theset_substitutecommand for details here.Source-code Syntax ColorizationTerminal source code is colorized viapygments. And with that you
can set the pygments color style, e.g. “colorful”, “paraiso-dark”. Seeset_style. Furthermore, we make use of terminal bold and emphasized
text in debugger output and help text. Of course, you can also turn
this off. You can use your ownpygments_style, provided you have a terminal that supports 256
colors. If your terminal supports the basic ANSI color sequences only,
we support that too in both dark and light themes.Command CompletionGNU readline command completion is available. Command completion is
not just a simple static list, but varies depending on the
context. For example, for frame-changing commands which take optional
numbers, on the list ofvalid numbersis considered.Terminal HandlingWe can adjust debugger output depending on the line width of your
terminal. If it changes, or you want to adjust it, seeset_width.Smart EvalIf you want to evaluate the current source line before it is run in
the code, useeval. To evaluate text of a common fragment of line,
such as the expression part of anifstatement, you can do that witheval?. Seeevalfor more information.Function BreakpointsMany Python debuggers only allow setting a breakpoint at a line event
and functions are treated like line numbers. But functions and lines
are fundamentally different. If I write:def five(): return 5this line means has three different kinds of things. First there is
the code in Python that defines functionfive()for the first
time. Then there is the function itself, and then there is some code
inside that function.In this debugger, you can give the name of afunctionby surrounding
adding()at the end:break five()Alsofivecould be a method of an object that is currently defined when thebreakpointcommand is given:self.five()More Stepping ControlSometimes you want small steps, and sometimes large stepping.This fundamental issue is handled in a couple ways:Step GranularityThere are nowstepeventandnexteventcommands with
aliases tos+,s>and so on. The plus-suffixed commands force
a different line on a subsequent stop, the dash-suffixed commands
don’t.  Suffixes>,<, and!specifycall,returnandexceptionevents respectively. And without a suffix you get
the default; this is set by theset differentcommand.Event Filtering and TracingBy default the debugger stops at every event:call,return,line,exception,c-call,c-exception. If you just want
to stop atlineevents (which is largely what you happens inpdb) you can. If however you just want to stop at calls and returns,
that’s possible too. Or pick some combination.In conjunction with handlingallevents by default, the event status is shown when stopped. The reason for stopping is also available viainfo program.Event Tracing of Calls and ReturnsI’m not sure why this was not done before. Probably because of the
lack of the ability to set and move by different granularities,
tracing calls and returns lead to too many uninteresting stops (such
as at the same place you just were at). Also, stopping on function
definitions probably also added to this tedium.Because we’re really handling return events, we can show you the return value. (pdbhas an “undocumented”retvalcommand that doesn’t seem to work.)Debugger Macros via Python Lambda expressionsThere are debugger macros.  Ingdb, there is amacrodebugger
command to extend debugger commands.However Python has its own rich programming language so it seems silly
to recreate the macro language that is ingdb. Simpler and more
powerful is just to use Python here. A debugger macro here is just a
lambda expression which returns a string or a list of strings. Each
string returned should be a debugger command.We also havealiasesfor the extremely simple situation where you
want to give an alias to an existing debugger command. But beware:
some commands, likestepinspect command suffixes and change their
behavior accordingly.We also envision a number of other ways to allow extension of this
debugger either through additional modules, or user-supplied debugger
command directories.Byte-code Instruction IntrospectionWe do more in the way of looking at the byte codes to give better information. Through this we can provide:askipcommand. It is like thejumpcommand, but you don’t have
to deal with line numbers.disassembly of code fragments. You can now disassemble relative to
the stack frames you are currently stopped at.Better interpretation of where you are when insideexecfileorexec. (But really though this is probably a Python compiler
misfeature.)Check that breakpoints are set only where they make sense.A more accurate determination of if you are at a function-definingdeforclassstatements (because the caller instruction containsMAKE_FUNCTIONorBUILD_CLASS.)Even without “deparsing” mentioned above, the ability to disassemble
where the PC is currently located (seeinfo pc), by line
number range or byte-offset range lets you tell exactly where you are
and code is getting run.Some Debugger Command Arguments can be Variables and ExpressionsCommands that take integer arguments likeup,list, ordisassembleallow you to use a Python expression which may include
local or global variables that evaluates to an integer. This
eliminates the need ingdbfor special “dollar” debugger
variables. (Note however because ofshlexparsing, expressions can’t
have embedded blanks.)Out-of-Process DebuggingYou can now debug your program in a different process or even a different computer on a different network!Related, is flexible support for remapping path names from file
system, e.g. that inside a docker container or on a remote filesystem
with locally-installed files. Seesubstfor more information.Egg, Wheel, and TarballsCan be installed via the usualpiporeasy_install. There is a
source tarball.How To Installhas
full instructions and installing from git and by other means.ModularityThe Debugger plays nice with other trace hooks. You can have several debugger objects.Many of the things listed below doesn’t directly effect end-users, but
it does eventually by way of more robust and featureful code. And
keeping developers happy is a good thing.(TM)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.I/O is it’s own layer. This simplifies interactive readline behavior from reading commands over a TCP socket.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.There is an experimental Python-friendly interface for front-endsmore testable. Much more unit and functional tests. More ofpydb’s integration test will eventually be added.DocumentationDocumentation:http://python3-trepan.readthedocs.orgSee Alsotrepan2: trepan debugger for Python 2trepanxpy: trepan debugger forx-python, the bytecode interpreter written in Pythonpydbgr: previous incarnation of the Python 2 debuggerpydb: even older incarnation of debugger (for very old Python 2)Tutorial: Tutorial for how to usehttps://github.com/rocky/trepan-xpy: Python debugger using this code to supportx-pythonhttps://pypi.python.org/pypi/uncompyle6: Python decompilerhttps://pypi.python.org/pypi/decompyle3: Python 3.7 and 3.8 decompilerhttps://pypi.python.org/pypi/xdis: cross-platform disassembler