Get the currently executing AST node of a frame, and other information
Project description
executing
This mini-package lets you get information about what a frame is currently doing, particularly the AST node being executed.
- Usage
- Installation
- How does it work?
- Is it reliable?
- Which nodes can it identify?
- Libraries that use this
Usage
Getting the AST node
import executing
node = executing.Source.executing(frame).node
Then node
will be an AST node (from the ast
standard library module) or None if the node couldn't be identified (which may happen often and should always be checked).
node
will always be the same instance for multiple calls with frames at the same point of execution.
If you have a traceback object, pass it directly to Source.executing()
rather than the tb_frame
attribute to get the correct node.
Getting the source code of the node
For this you will need to separately install the asttokens
library, then obtain an ASTTokens
object:
executing.Source.executing(frame).source.asttokens()
or:
executing.Source.for_frame(frame).asttokens()
or use one of the convenience methods:
executing.Source.executing(frame).text()
executing.Source.executing(frame).text_range()
Getting the __qualname__
of the current function
executing.Source.executing(frame).code_qualname()
or:
executing.Source.for_frame(frame).code_qualname(frame.f_code)
The Source
class
Everything goes through the Source
class. Only one instance of the class is created for each filename. Subclassing it to add more attributes on creation or methods is recommended. The classmethods such as executing
will respect this. See the source code and docstrings for more detail.
Installation
pip install executing
If you don't like that you can just copy the file executing.py
, there are no dependencies (but of course you won't get updates).
How does it work?
Suppose the frame is executing this line:
self.foo(bar.x)
and in particular it's currently obtaining the attribute self.foo
. Looking at the bytecode, specifically frame.f_code.co_code[frame.f_lasti]
, we can tell that it's loading an attribute, but it's not obvious which one. We can narrow down the statement being executed using frame.f_lineno
and find the two ast.Attribute
nodes representing self.foo
and bar.x
. How do we find out which one it is, without recreating the entire compiler in Python?
The trick is to modify the AST slightly for each candidate expression and observe the changes in the bytecode instructions. We change the AST to this:
(self.foo ** 'longuniqueconstant')(bar.x)
and compile it, and the bytecode will be almost the same but there will be two new instructions:
LOAD_CONST 'longuniqueconstant'
BINARY_POWER
and just before that will be a LOAD_ATTR
instruction corresponding to self.foo
. Seeing that it's in the same position as the original instruction lets us know we've found our match.
Is it reliable?
Yes - if it identifies a node, you can trust that it's identified the correct one. The tests are very thorough - in addition to unit tests which check various situations directly, there are property tests against a large number of files (see the filenames printed in this build) with real code. Specifically, for each file, the tests:
- Identify as many nodes as possible from all the bytecode instructions in the file, and assert that they are all distinct
- Find all the nodes that should be identifiable, and assert that they were indeed identified somewhere
In other words, it shows that there is a one-to-one mapping between the nodes and the instructions that can be handled. This leaves very little room for a bug to creep in.
Furthermore, executing
checks that the instructions compiled from the modified AST exactly match the original code save for a few small known exceptions. This accounts for all the quirks and optimisations in the interpreter.
Which nodes can it identify?
Currently it works in almost all cases for the following ast
nodes:
Call
, e.g.self.foo(bar)
Attribute
, e.g.point.x
Subscript
, e.g.lst[1]
BinOp
, e.g.x + y
(doesn't includeand
andor
)UnaryOp
, e.g.-n
(includesnot
but only works sometimes)Compare
e.g.a < b
(not for chains such as0 < p < 1
)
The plan is to extend to more operations in the future.
Projects that use this
My Projects
stack_data
: Extracts data from stack frames and tracebacks, particularly to display more useful tracebacks than the default. Also uses another related library of mine:pure_eval
.futurecoder
: Highlights the executing node in tracebacks usingexecuting
viastack_data
, and provides debugging withsnoop
.snoop
: A feature-rich and convenient debugging library. Usesexecuting
to show the operation which caused an exception and to allow thepp
function to display the source of its arguments.heartrate
: A simple real time visualisation of the execution of a Python program. Usesexecuting
to highlight currently executing operations, particularly in each frame of the stack trace.sorcery
: Dark magic delights in Python. Usesexecuting
to let special callables called spells know where they're being called from.
Projects I've contributed to
IPython
: Highlights the executing node in tracebacks usingexecuting
viastack_data
.icecream
: 🍦 Sweet and creamy print debugging. Usesexecuting
to identify whereic
is called and print its arguments.friendly_traceback
: Usesstack_data
andexecuting
to pinpoint the cause of errors and provide helpful explanations.python-devtools
: Usesexecuting
for print debugging similar toicecream
.sentry_sdk
: Add the integrationsentry_sdk.integrations.executingExecutingIntegration()
to show the function__qualname__
in each frame in sentry events.varname
: Dark magics about variable names in python. Usesexecuting
to find where its various magical functions likevarname
andnameof
are called from.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for executing-2.1.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8d63781349375b5ebccc3142f4b30350c0cd9c79f921cde38be2be4637e98eaf |
|
MD5 | 99bcfdc77ecdd522bf2fee68c9d32f78 |
|
BLAKE2b-256 | b5fdafcd0496feca3276f509df3dbd5dae726fcc756f1a08d9e25abe1733f962 |