equip package

Subpackages

• equip.analysis package
  • Subpackages
    • equip.analysis.graph package
      • Submodules
        • equip.analysis.graph.dominators
        • equip.analysis.graph.graphs
        • equip.analysis.graph.io
        • equip.analysis.graph.traversals
      • Module contents
        • equip.analysis.graph
  • Submodules
    • equip.analysis.block
    • equip.analysis.flow
  • Module contents
    • equip.analysis
• equip.bytecode package
  • Submodules
    • equip.bytecode.code
    • equip.bytecode.decl
    • equip.bytecode.utils
  • Module contents
    • equip.bytecode
• equip.rewriter package
  • Submodules
    • equip.rewriter.merger
    • equip.rewriter.simple
  • Module contents
    • equip.rewriter
• equip.utils package
  • Submodules
    • equip.utils.files
    • equip.utils.log
  • Module contents
• equip.visitors package
  • Submodules
    • equip.visitors.bytecode
    • equip.visitors.classes
    • equip.visitors.methods
    • equip.visitors.modules
  • Module contents
    • equip.visitors

Submodules

equip.instrument

Main interface to handle the instrumentation and run the visitors.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.

class equip.instrument.Instrumentation(location=None)

Bases: object

Main class for handling the instrumentation. The typical workflow is:

1. Set the location from the ctor or using the location setter
2. Update options, such as force-rebuild
3. Call prepare_program to scan the file system for source/bytecode
4. Register any on_enter/on_exit instrumentation callbacks
5. apply the instrumentation using a customer visitor

KNOWN_OPTIONS = ('force-rebuild',)

The list of known options

apply(visitor, rewrite=False)

Runs the visitor over all matching types (e.g., MethodDeclaration, etc.).

Parameters:

• visitor – The instance of the visitor to run over the program.
• rewrite – Whether the instrumentation should overwrite the bytecode file (pyc) at the end. Default is False.

get_option(key)

Gets the value of an option. Defaults to None.

Parameters:key – The name of the option.

instrument(visitor, bytecode_file, rewrite=False)

Loads the representation of the bytecode in bytecode_file, and apply the visitor to the representation.

Parameters:

• visitor – The instance of the visitor to run over the representation of the bytecode.
• bytecode_file – Absolute path of the file containing the bytecode (pyc).
• rewrite – Whether the instrumentation should overwrite the bytecode file (pyc) at the end. Default is False.

location

The path that contains the bytecode of the application to instrument. The path can either be a string or an iterable.

on_enter(python_code, import_code=None)

Inserts the python_code at the beginning of the module inside an if statement. The resulting injected code looks like this:

if __name__ == '__main__':
  python_code

Parameters:

• python_code – Python code to inject before the module gets executed (if it’s executed under main). The code is not executed if it’s not under main.
• import_code – Python code that contains the import statements that might be required by the injected python_code. Defaults to None.

on_exit(python_code, import_code=None)

Inserts the python_code at the end of the module inside an if statement. The resulting injected code looks like this:

if __name__ == '__main__':
  python_code

Parameters:

• python_code – Python code to inject after the module gets executed (if it’s executed under main). The code is not executed if it’s not under main.
• import_code – Python code that contains the import statements that might be required by the injected python_code. Defaults to None.

prepare_program()

Builds the representation of the program, and compiles all source files if it’s either necessary (e.g., missing bytecode for existing source) or if the force-rebuild option is set.

set_option(key, value=True)

Sets one of the options used later one by the instrumentation. The available options are listed in KNOWN_OPTIONS.

Parameters:

• key – The name of the option to set.
• value – The value of the option. Defaults to True.

validate()

Debugging info for the instrumented bytecode. Iterates again over all the bytecode and dumps the current (instrmented) bytecode.

equip.prog

Handles the current program for instrumentation.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.

class equip.prog.Program(instrumentation)

Bases: object

Captures the sources and binaries from the current program to instrument.

bytecode_files

The list of pyc files.

compile_program()

Compiles the program.

create_program(skip_rebuild=False)

Creates the structure of the program with its source files and binary files. When the Instrument option force-rebuild is set, it will trigger the compilation of all python source files.

Parameters:skip_rebuild – Force skipping the build. Mostly here due to the recursive nature of this function.

static split_program_source_bc(lst)

Module contents

equip

Bytecode instrumentation framework for Python.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.