equip.bytecode package

Submodules

equip.bytecode.code

Parsing and representation of the supplied bytecode.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.

class equip.bytecode.code.BytecodeObject(pyc_file, lazy_load=True)

Bases: object

This class parses the bytecode from a file and constructs the representation from it. The result is:

• One module (type: ModuleDeclaration)
• The bytecode expanded into intelligible structure.
• Construction of nested declarations, and hierarchy of declaration types.

accept(visitor)

Runs the visitor over the nested declarations found in the this module, or the entire bytecode if it’s a BytecodeVisitor.

add_enter_code(python_code, import_code=None)

Adds enter callback in the module. The callback code (both import_code and python_code) is wrapped in a main test if statement:

if __name__ == '__main__':
  import_code
  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.

add_exit_code(python_code, import_code=None)

Adds exit callback in the module. The callback code (both import_code and python_code) is wrapped in a main test if statement:

if __name__ == '__main__':
  import_code
  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.

build_representation()

Builds the internal representation of declarations and how they relate to each other. It works by creating a map of type/method declaration indices, and then associate the bytecode for each of them.

When all declarations are created, the parenting process runs and creates the tree structure of the decalrations, such as:

ModuleDeclaration()
  - TypeDeclaration(name='SomeClass')
     - MethodDeclaration#lineno(name='methodOfSomeClass')
     - MethodDeclaration#lineno(name='otherMethodOfSomeClass')

This representation is required to run the visitors.

static build_tree(root, indent='')

Returns a string that represents the tree of Declaration types.

declarations

Returns a set of all the declarations found in the current bytecode.

static finalize_decl_object(kind, acc_data)

static find_classes_methods(bytecode)

Finds the indices of the classes and methods declared in the bytecode. This is done by matching code_object of the declaration and the MAKE_FUNCTION or BUILD_CLASS opcode.

get_bytecode()

Returns the current translated bytecode.

get_decl(code_object=None, method_name=None, type_name=None)

Returns the declaration associated to the code_object co, or supplied name.

Warning: This is only valid until the rewriter is called on the declarations.

Parameters:

• code_object – Python code object type
• method_name – Name of the method.
• type_name – Name of the type.

static get_formal_params(code_object)

Returns the ordered list of formal parameters (arguments) of a method.

Parameters:code_object – The code object of the method.

static get_imports_from_bytecode(code_object, bytecode)

Parses the import statements from the bytecode and constructs a list of ImportDeclaration.

static get_last_import_ref(bytecode, code_object)

Find the last reference of an import statement in the bytecode.

get_module()

Returns the ModuleDeclaration associated with the current bytecode.

static get_parsed_code(code_object)

has_changes

Returns True if any change was performed on the module. This is used to know if we need to rewrite or not a pyc file.

load_bytecode(code_object)

static next_code_object(bytecode, index)

parse()

Parses the binary file (pyc) and extract the bytecode out of it. Keeps the magic number as well as the timestamp for serialization.

parse_code(co)

Parses a Python code object. Mostly useful for testing.

static parse_code_object(code_object, bytecode)

Parses the bytecode (co_code field of the code object) and dereferences the oparg for later analysis.

Parameters:

• code_object – The code object containing the bytecode to analyze
• bytecode – The list that will be used to append the expanded bytecode sequences.

static parse_imports(main_module, bytecode)

Extracts and adds import statements to the ModuleDeclaration.

static prev_code_object(bytecode, index)

write()

Persists the changes in the bytecode. This overwrites the current file that contains the bytecode with the new bytecode while preserving the timestamp.

Note that the magic number if changed to be the one from the current Python version that runs the instrumentation process.

equip.bytecode.decl

Structured representation of Module, Types, Method, Imports.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.

class equip.bytecode.decl.Declaration(kind, _code_object)

Bases: object

Base class for the declaration types of object.

FIELD = 4

IMPORT = 5

METHOD = 3

MODULE = 1

TYPE = 2

accept(visitor)

add_child(child)

Adds a child to this declaration.

Parameters:child – A Declaration that is a child of the current declaration.

bytecode

Returns the bytecode associated with this declaration.

bytecode_object

children

Returns the children of this declaration.

code_object

end_lineno

Returns the end line number of the declaration.

get_start_lineno()

has_changes

is_field()

is_import()

is_method()

is_module()

is_type()

kind

lines

A tuple of start/end line numbers that encapsulates this declaration.

parent

Returns the parent of this declaration or None if there is no parent (e.g., for a ModuleDeclaration).

parent_class

Returns the parent class (a TypeDeclaration) for this declaration.

parent_method

Returns the parent method (a MethodDeclaration) for this declaration.

parent_module

Returns the parent module (a ModuleDeclaration) for this declaration.

start_lineno

Returns the start line number of the declaration.

update_nested_code_object(original_co, new_co)

class equip.bytecode.decl.FieldDeclaration(field_name, code_object)

Bases: equip.bytecode.decl.Declaration

field_name

class equip.bytecode.decl.ImportDeclaration(code_object)

Bases: equip.bytecode.decl.Declaration

Models an import statement. It handles relatives/absolute imports, as well as aliases.

aliases

dots

live_names

root

star

class equip.bytecode.decl.MethodDeclaration(method_name, code_object)

Bases: equip.bytecode.decl.Declaration

The declaration of a method or a function.

body

formal_parameters

is_lambda

labels

method_name

nested_types

class equip.bytecode.decl.ModuleDeclaration(module_path, code_object)

Bases: equip.bytecode.decl.Declaration

The module is the object that captures everything under one pyc file. It contains nested classes and functions, as well as import statements.

add_import(importDecl)

classes

functions

imports

module_path

class equip.bytecode.decl.TypeDeclaration(type_name, code_object)

Bases: equip.bytecode.decl.Declaration

Represent a class declaration. It has a name, as well as a hierarchy (superclass). The type contains several methods and fields, and can have nested types.

fields

methods

Returns a list of MethodDeclaration that belong to this type.

nested_types

Returns a list of TypeDeclaration that belong to this type.

superclasses

type_name

Returns the name of the type.

equip.bytecode.utils

Utilities for bytecode interaction.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.

equip.bytecode.utils.get_debug_code_object_dict(code_object)

equip.bytecode.utils.get_debug_code_object_info(code_object)

equip.bytecode.utils.show_bytecode(bytecode, start=0, end=4294967296)

equip.bytecode.utils.update_nested_code_object(main_co, original_co, new_co)

Module contents

equip.bytecode

Operations and representations related to parsing the bytecode and extracting its structure.

copyright:

3. 2014 by Romain Gaucher (@rgaucher)

license:

Apache 2, see LICENSE for more details.