Core APIs

jawa.cf module

ClassFile support.

The jawa.cf module provides tools for working with JVM .class ClassFiles.

class jawa.cf.ClassFile(fio=None)[source]

Bases: object

Implements the JVM ClassFile (files typically ending in .class).

To open an existing ClassFile:

from jawa import ClassFile
with open('HelloWorld.class') as fin:
    cf = ClassFile(fin)

To save a newly created or modified ClassFile:

with open('HelloWorld.class', 'wb') as fout:
    cf.save(fout)

To create a new ClassFile, use the helper create():

from jawa import ClassFile
cf = ClassFile.create('HelloWorld')
with open('HelloWorld.class', 'wb') as fout:
    cf.save(fout)

create() sets up some reasonable defaults equivelent to:

public class HelloWorld extends java.lang.Object{
}
Parameters:fio – any file-like object providing .read().
MAGIC = 3405691582

The JVM ClassFile magic number.

access_flags
attributes

The AttributeTable for this class.

constants

The ConstantPool for this class.

classmethod create(this, super_='java/lang/Object')[source]

A utility which sets up reasonable defaults for a new public class.

Parameters:
  • this – The name of this class.
  • super – The name of this class’s superclass.
fields

The FieldTable for this class.

interfaces

A list of direct superinterfaces of this class as indexes into the constant pool, in left-to-right order.

methods

The MethodTable for this class.

save(fout)[source]

Saves the class to the file-like object fout.

super_

The ConstantClass which represents this class’s superclass.

this

The ConstantClass which represents this class.

version

The ClassVersion for this class.

Example:

>>> cf = ClassFile.create('HelloWorld')
>>> cf.version = 51, 0
>>> print(cf.version)
ClassVersion(major=51, minor=0)
>>> print(cf.version.major)
51
class jawa.cf.ClassVersion[source]

Bases: jawa.cf.ClassVersion

ClassFile file format version.

human

A human-readable string identifying this version.

If the version is unknown, None is returned instead.

jawa.assemble module

class jawa.assemble.Label(name)

Bases: tuple

name

Alias for field number 0

jawa.assemble.assemble(code)[source]

Assemble the given iterable of mnemonics, operands, and lables.

A convienience over constructing individual Instruction and Operand objects, the output of this function can be directly piped to assemble() to produce executable bytecode.

As a simple example, lets produce an infinite loop:

>>> from jawa.assemble import assemble, Label
>>> print(list(assemble((
...     Label('start'),
...     ('goto', Label('start'))
... ))))
[Instruction(mnemonic='goto', opcode=167, operands=[
    Operand(op_type=40, value=0)], pos=0)]

For a more complex example, see examples/hello_world.py.

jawa.attribute module

class jawa.attribute.AttributeTable(cf, parent=None)[source]

Bases: object

append(attribute)[source]
cf

The ClassFile that owns this Attribute, if any.

create(type_, *args, **kwargs)[source]

Creates a new attribute of type_, appending it to the attribute table and returning it.

find(name=None, f=None)[source]
find_one(*args, **kwargs)[source]

Same as find() but returns only the first result, or None if nothing was found.

pack(fout)[source]

Write the AttributeTable to the file-like object fout.

Note

Advanced usage only. You will typically never need to call this method as it will be calle=d for you when saving a ClassFile.

Parameters:fout – Any file-like object providing write()
parent

The parent attribute, if any.

If this AttributeTable belongs to another Attribute, this will reference that attribute. For example, when parsing a StackMapTable attribute, this would point to the owning Code attribute.

unpack(fio)[source]

Read the ConstantPool from the file-like object fio.

Note

Advanced usage only. You will typically never need to call this method as it will be called for you when loading a ClassFile.

Parameters:fio – Any file-like object providing read()
class jawa.attribute.Attribute(table, name_index=None)[source]

Bases: object

cf

The ClassFile that owns this attribute, if any.

info

This attribute packed into its on-disk representation.

name

The ConstantUtf8 with the name of this attribute.

pack()[source]

This attribute packed into its on-disk representation.

table

The AttributeTable that owns this attribute, if any.

unpack(info)[source]

Parses an instance of this attribute from the blob info.

class jawa.attribute.UnknownAttribute(table, name_index=None)[source]

Bases: jawa.attribute.Attribute

info
unpack(info)[source]

jawa.constants module

class jawa.constants.ConstantPool[source]

Bases: object

append(constant)[source]

Appends a new constant to the end of the pool.

create_class(name)[source]

Creates a new ConstantClass, adding it to the pool and returning it.

Parameters:name – The name of the new class.
create_double(value)[source]

Creates a new ConstantDouble, adding it to the pool and returning it.

Parameters:value – The value of the new Double.
create_field_ref(class_, field, descriptor)[source]

Creates a new ConstantFieldRef, adding it to the pool and returning it.

Parameters:
  • class – The name of the class to which field belongs.
  • field – The name of the field.
  • descriptor – The descriptor for field.
create_float(value)[source]

Creates a new ConstantFloat, adding it to the pool and returning it.

Parameters:value – The value of the new float.
create_integer(value)[source]

Creates a new ConstantInteger, adding it to the pool and returning it.

Parameters:value – The value of the new integer.
create_interface_method_ref(class_, if_method, descriptor)[source]

Creates a new ConstantInterfaceMethodRef, adding it to the pool and returning it.

Parameters:
  • class – The name of the class to which if_method belongs.
  • if_method – The name of the interface method.
  • descriptor – The descriptor for if_method.
create_long(value)[source]

Creates a new ConstantLong, adding it to the pool and returning it.

Parameters:value – The value of the new long.
create_method_ref(class_, method, descriptor)[source]

Creates a new ConstantMethodRef, adding it to the pool and returning it.

Parameters:
  • class – The name of the class to which method belongs.
  • method – The name of the method.
  • descriptor – The descriptor for method.
create_name_and_type(name, descriptor)[source]

Creates a new ConstantNameAndType, adding it to the pool and returning it.

Parameters:
  • name – The name of the class.
  • descriptor – The descriptor for name.
create_string(value)[source]

Creates a new ConstantString, adding it to the pool and returning it.

Parameters:value – The value of the new string as a UTF8 string.
create_utf8(value)[source]

Creates a new ConstantUTF8, adding it to the pool and returning it.

Parameters:value – The value of the new UTF8 string.
find(type_=None, f=None)[source]

Iterates over the pool, yielding each matching Constant. Calling without any arguments is equivelent to iterating over the pool.

Parameters:
  • type – Any subclass of Constant or None.
  • f – Any callable which takes one argument (the constant).
find_one(*args, **kwargs)[source]

Same as find() but returns only the first result, or None if nothing was found.

get(index)[source]

Returns the Constant at index, raising a KeyError if it does not exist.

pack(fout)[source]

Write the ConstantPool to the file-like object fout.

Note

Advanced usage only. You will typically never need to call this method as it will be calle=d for you when saving a ClassFile.

Parameters:fout – Any file-like object providing write()
raw_count

The number of Constants in the ConstantPool, including padding.

unpack(fio)[source]

Read the ConstantPool from the file-like object fio.

Note

Advanced usage only. You will typically never need to call this method as it will be called for you when loading a ClassFile.

Parameters:fio – Any file-like object providing read()
class jawa.constants.Constant(pool, index)[source]

Bases: object

The base class for all Constant* types.

index

The index of this constant in the constant pool.

pool

The constant pool this constant belongs to.

class jawa.constants.ConstantUTF8(pool, index, value)[source]

Bases: jawa.constants.Constant

TAG = 1
class jawa.constants.ConstantClass(pool, index, name_index)[source]

Bases: jawa.constants.Constant

TAG = 7
name
class jawa.constants.ConstantString(pool, index, string_index)[source]

Bases: jawa.constants.Constant

TAG = 8
string
class jawa.constants.ConstantRef(pool, index, class_index, name_and_type_index)[source]

Bases: jawa.constants.Constant

class_
name_and_type
class jawa.constants.ConstantFieldRef(pool, index, class_index, name_and_type_index)[source]

Bases: jawa.constants.ConstantRef

TAG = 9
class jawa.constants.ConstantMethodRef(pool, index, class_index, name_and_type_index)[source]

Bases: jawa.constants.ConstantRef

TAG = 10
class jawa.constants.ConstantInterfaceMethodRef(pool, index, class_index, name_and_type_index)[source]

Bases: jawa.constants.ConstantRef

TAG = 11
class jawa.constants.ConstantInteger(pool, index, value)[source]

Bases: jawa.constants.ConstantNumber

TAG = 3
class jawa.constants.ConstantFloat(pool, index, value)[source]

Bases: jawa.constants.ConstantNumber

TAG = 4
class jawa.constants.ConstantLong(pool, index, value)[source]

Bases: jawa.constants.ConstantNumber

TAG = 5
class jawa.constants.ConstantDouble(pool, index, value)[source]

Bases: jawa.constants.ConstantNumber

TAG = 6
class jawa.constants.ConstantNameAndType(pool, index, name_index, descriptor_index)[source]

Bases: jawa.constants.Constant

TAG = 12
descriptor
name

jawa.fields module

class jawa.fields.FieldTable(cf)[source]

Bases: object

append(field)[source]
create(name, descriptor)[source]

Creates a new field from name and descriptor. For example:

>>> from jawa import ClassFile
>>> cf = ClassFile.create('BeerCounter')
>>> field = cf.fields.create('BeerCount', 'I')
create_static(name, descriptor, value)[source]

A shortcut for creating a static field with a ConstantValueAttribute set to the Constant value. For example, to create a string with the classic “Hello World!”:

>>> from jawa import ClassFile
>>> cf = ClassFile.create('BeerCounter')
>>> field = cf.fields.create_static(
...    'HelloWorld',
...    'Ljava/lang/String;',
...    cf.constants.create_string('Hello World!')
... )
find(name=None, type_=None, f=None)[source]

Iterates over the fields table, yielding each matching method. Calling without any arguments is equivelent to iterating over the table.

Parameters:
  • name – The name of the field(s) to find.
  • type – The field descriptor (Ex: ‘I’)
  • f – Any callable which takes one argument (the field).
find_and_remove(f)[source]

Removes any and all fields for which f(field) returns True.

find_one(*args, **kwargs)[source]

Same as find() but returns only the first result, or None if nothing was found.

pack(fout)[source]

Write the FieldTable to the file-like object fout.

Note

Advanced usage only. You will typically never need to call this method as it will be calle=d for you when saving a ClassFile.

Parameters:fout – Any file-like object providing write()
remove(field)[source]

Removes a Field from the table by identity.

unpack(fio)[source]

Read the FieldTable from the file-like object fio.

Note

Advanced usage only. You will typically never need to call this method as it will be called for you when loading a ClassFile.

Parameters:fio – Any file-like object providing read()
class jawa.fields.Field(cf)[source]

Bases: object

access_flags
attributes
descriptor
name
pack(fout)[source]

Write the Field to the file-like object fout.

Note

Advanced usage only. You will typically never need to call this method as it will be calle=d for you when saving a ClassFile.

Parameters:fout – Any file-like object providing write()
unpack(fio)[source]

Read the Field from the file-like object fio.

Note

Advanced usage only. You will typically never need to call this method as it will be called for you when loading a ClassFile.

Parameters:fio – Any file-like object providing read()
value

A shortcut for the field’s ConstantValue attribute, should one exist.

jawa.methods module

class jawa.methods.MethodTable(cf)[source]

Bases: object

append(method)[source]
create(name, descriptor, code=None)[source]

Creates a new method from name and descriptor. If code is not None, add a Code attribute to this method.

find(name=None, args=None, returns=None, f=None)[source]

Iterates over the methods table, yielding each matching method. Calling without any arguments is equivelent to iterating over the table. For example, to get all methods that take three integers and return void:

for method in cf.methods.find(args='III', returns='V'):
    print(method.name.value)

Or to get all private methods:

is_private = lambda m: m.access_flags.acc_private
for method in cf.methods.find(f=is_private):
    print method.name.value
Parameters:
  • name – The name of the method(s) to find.
  • args – The arguments descriptor (ex: III)
  • returns – The returns descriptor (Ex: V)
  • f – Any callable which takes one argument (the method).
find_and_remove(f)[source]

Removes any and all methods for which f(method) returns True.

find_one(*args, **kwargs)[source]

Same as find() but returns only the first result, or None if nothing was found.

pack(fout)[source]

Write the MethodTable to the file-like object fout.

Note

Advanced usage only. You will typically never need to call this method as it will be calle=d for you when saving a ClassFile.

Parameters:fout – Any file-like object providing write()
remove(method)[source]

Removes a method from the table by identity.

unpack(fio)[source]

Read the MethodTable from the file-like object fio.

Note

Advanced usage only. You will typically never need to call this method as it will be called for you when loading a ClassFile.

Parameters:fio – Any file-like object providing read()
class jawa.methods.Method(cf)[source]

Bases: object

access_flags
args
attributes
code

A shortcut for:

method.attributes.find_one(name='Code')
descriptor
name
pack(fout)[source]

Write the Method to the file-like object fout.

Note

Advanced usage only. You will typically never need to call this method as it will be calle=d for you when saving a ClassFile.

Parameters:fout – Any file-like object providing write()
returns
unpack(fio)[source]

Read the Method from the file-like object fio.

Note

Advanced usage only. You will typically never need to call this method as it will be called for you when loading a ClassFile.

Parameters:fio – Any file-like object providing read()