Skip to content
Python cross version bytecode/wordcode assembler
Python Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test More tests May 25, 2018
xasm Improve docs May 5, 2019
.gitignore More tests May 25, 2018
HOW-TO-USE.rst Update HOW-TO-USE.rst May 25, 2019
LICENSE.gpl2 Administrivia Jul 15, 2017
MANIFEST.in Add link Jul 15, 2017
Makefile Add some sort of testing Jul 21, 2017
README.rst Update README.rst May 25, 2019
__pkginfo__.py Version hell Apr 5, 2019
setup.py

README.rst

xasm

NOTE: this is in beta

A Cross-Python bytecode Assembler

Introduction

The Python xasm module has routines for assembly, and has a command to assemble bytecode for several different versions of Python.

Here are some potential uses:

  • Make small patches to existing Python bytecode when you don’t have source
  • Craft custom and efficient bytecode
  • Write an instruction-level optimizing compiler
  • Experiment with and learn about Python bytecode
  • Foil uncompyle6 so that it can’t disassemble bytecode (at least for now)

This will support bytecodes from Python version 1.5 to 3.8 or so.

The code requires Python 2.7 or later.

Assembly files

More detail will be filled in, but some principles:

  • Preferred extension for Python assembly is .pyasm
  • assembly is designed to work with the output of pydisasm
  • Assembly file labels are at the beginning of the line and end in a colon, e.g. 'END_IF:'
  • instruction offsets in the assembly file are ignored and don't need to be entered
  • in those instructions that refer to offsets, if the if the operand is an int, exactly that value will be used for the operand. Otherwise we will look for labels and match up with that

Installation

This uses setup.py, so it follows the standard Python routine:

pip install -e .
pip install -r requirements-dev.txt
python setup.py install # may need sudo
# or if you have pyenv:
python setup.py develop

A GNU makefile is also provided so make install (possibly as root or sudo) will do the steps above.

Example Assembly File

For this Python source code:

def five():
    return 5

print(five())

Here is an assembly for the above:

# Python bytecode 3.6 (3379)

# Method Name:       five
# Filename:          /tmp/five.pl
# Argument count:    0
# Kw-only arguments: 0
# Number of locals:  0
# Stack size:        1
# Flags:             0x00000043 (NOFREE | NEWLOCALS | OPTIMIZED)
# First Line:        1
# Constants:
#    0: None
#    1: 5
  2:
            LOAD_CONST           (5)
            RETURN_VALUE


# Method Name:       <module>
# Filename:          /tmp/five.pl
# Argument count:    0
# Kw-only arguments: 0
# Number of locals:  0
# Stack size:        2
# Flags:             0x00000040 (NOFREE)
# First Line:        1
# Constants:
#    0: <code object five at 0x0000>
#    1: 'five'
#    2: None
# Names:
#    0: five
#    1: print
  1:
            LOAD_CONST           0 (<code object five at 0x0000>)
            LOAD_CONST           ('five')
            MAKE_FUNCTION        0
            STORE_NAME           (five)

  3:
            LOAD_NAME            (print)
            LOAD_NAME            (five)
            CALL_FUNCTION        0
            CALL_FUNCTION        1
            POP_TOP
            LOAD_CONST           (None)
            RETURN_VALUE

The above can be created automatically from Python source code using the pydisasm command from xdis:

pydisasm --asm /tmp/five.pyc

In the example above though, I have shortend and simplified the result.

Usage

To create a python bytecode file from an assemble file, run:

pyc-xasm [OPTIONS] ASM_PATH

For usage help pyc-xasm --help

To convert a python bytecode from one bytecode to another, run:

pyc-convert [OPTIONS] INPUT_PYC [OUTPUT_PYC]

For usage help pyc-convert --help

See Also

You can’t perform that action at this time.