Skip to main content

Python bytecode instrumentation framework

Project description

equip is a small library that helps with Python bytecode instrumentation. Its API is designed to be small and flexible to enable a wide range of possible instrumentations.

The instrumentation is designed around the injection of bytecode inside the bytecode of the program to be instrumented. However, the developer does not need to know anything about the Python bytecode.

The following example shows how to write a simple instrumentation tool that will print all method called in the program, along with its arguments:

import sys
import equip
from equip import Instrumentation, MethodVisitor, SimpleRewriter

BEFORE_CODE = """
print ">> START"
print "[CALL] {file_name}::{method_name}:{lineno}", {arguments}
print "<< END"
"""

class MethodInstr(MethodVisitor):
  def __init__(self):
    MethodVisitor.__init__(self)

  def visit(self, meth_decl):
    rewriter = SimpleRewriter(meth_decl)
    rewriter.insert_before(BEFORE_CODE)

instr_visitor = MethodInstr()
instr = Instrumentation(sys.argv[1])
if not instr.prepare_program():
  return
instr.apply(instr_visitor, rewrite=True)

This program requires the path to the program to instrument, and will compile the source to generate the bytecode to instrument. All bytecode will be loaded into its representation, and the MethodInstr visitor will be called on all method declarations.

When a change is required (i.e., the code actually needs to be instrumented), the Instrumentation will overwrite the pyc file.

Running the instrumented program afterwards does not require anything but executing it as you would usually do. If the injected code has external dependencies, you can simply modify the PYTHONPATH to point to the required modules.

Project details


Release history Release notifications | RSS feed

This version

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

equip-0.1.tar.gz (25.1 kB view details)

Uploaded Source

Built Distribution

equip-0.1-py2.py3-none-any.whl (33.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file equip-0.1.tar.gz.

File metadata

  • Download URL: equip-0.1.tar.gz
  • Upload date:
  • Size: 25.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for equip-0.1.tar.gz
Algorithm Hash digest
SHA256 d667c25f9b4bb9d060eef799b6fed715565c1840c754c1f257292083bd1883ea
MD5 9f7b8826b441d330bf90fbf97aa9fe49
BLAKE2b-256 c1d56b0ffdd5255e5479894bc0a79430216843ab0c6f3591a8a7a9909e829660

See more details on using hashes here.

File details

Details for the file equip-0.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for equip-0.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 5588c763c7aceb034a90661432b88cca4a229d522ecb71fa790c58e3cefa5601
MD5 c370883ebd010e2a306607a233dab794
BLAKE2b-256 6cf9cfbe8302096d75f4cbc56c2785c9a02b36c44e4639283fa2e7c98b0257b9

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page