Metadata-Version: 2.0
Name: xasm
Version: 0.1.0
Summary: Python cross-version byte-code assembler
Home-page: https://github.com/rocky/python-xasm/
Author: Rocky Bernstein
Author-email: rb@dustyfeet.com
License: GPL-2.0
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.4
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules

xasm
====

*NOTE: this is in an early beta stage*

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 ot existing Python bytecode when you don't have source
* Write more efficient bytecode
* Write an instruction-level optimizing compiler
* Experiment and learn about Python Bytecode
* Foil uncompyle6_ in being able to disassemble bytecode

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

The code requires Python 2.7 or later.

Assembly files
--------------

More detail will be filled in, but some principles:

* Prefered extension for Python assembly is `.pyasm`
* assembly is designed to work with the output of `pydisasm`
* Assesembly file lables 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 enteed
* 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 -r requirements.txt
    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 :code:`make install` (possibly as root or
sudo) will do the steps above.

Usage
-----

Run

::

     pyxasm  <Python assembler file>


For usage help  `pyxasm --help`



See Also
--------
* https://github.com/rocky/python-xdis : Cross Python version dissasemble
* https://github.com/rocky/python-xasm/blob/master/HOW-TO-USE.rst : How to write an assembler file

.. _uncompyle6: https://github.com/rocky/python-uncompyle6



