|PyPI Installs| |Latest Version| |Supported Python Versions|
|packagestatus|
xdis
====
A Cross-Python bytecode disassembler, bytecode/wordcode and magic-number manipulation library/package.
Introduction
------------
The Python dis_ module allows you to disassemble bytecode from the same
version of Python that you are running on. But what about bytecode from
different versions?
That's what this package is for. It can "marshal load" Python
bytecodes from different versions of Python. The command-line routine
*pydisasm* will show disassembly output using the most modern Python
disassembly conventions in a variety of user-specified formats. Some
of these formats like `extended` and `extended-format` are the most
advanced of any Python disassembler I know of because they can show
expression-tree on operators. See the [Disasembler
Example][#disasembler-example] below.
Also, if you need to modify and write bytecode, the routines here can
be of help. There are routines to pack and unpack the read-only tuples
in Python's Code type. For interoperability between Python 2 and 3 we
provide our own versions of the Code type, and we provide routines to
reduce the tedium in writing a bytecode file.
This package also has an extensive knowledge of Python bytecode magic
numbers, including Pypy and others, and how to translate from
``sys.sys_info`` major, minor, and release numbers to the corresponding
magic value.
So if you want to write a cross-version assembler, or a
bytecode-level optimizer this package may also be useful. In addition
to the kinds of instruction categorization that ``dis``` offers, we have
additional categories for things that would be useful in such a
bytecode assembler, optimizer, or decompiler.
The programs here accept bytecodes from Python version 1.0 to 3.11 or
so. The code requires Python 2.4 or later and has been tested on
Python running lots of Python versions.
When installing, except for the most recent versions of Python, use
the Python egg or wheel that matches that version, e.g. ``xdis-6.0.2-py3.3.egg``, ``xdis-6.0.2-py33-none-any.whl``.
Of course for versions that pre-date wheel's, like Python 2.6, you will have to use eggs.
To install older versions for from source in git use the branch
``python-2.4-to-2.7`` for Python versions from 2.4 to 2.7,
``python-3.1-to-3.2`` for Python versions from 3.1 to 3.2,
``python-3.3-to-3.5`` for Python versions from 3.3 to 3.5. The master
branch handles Python 3.6 and later.
Installation
------------
The standard Python routine:
::
$ pip install -e .
$ pip install -r requirements-dev.txt
A GNU makefile is also provided so ``make install`` (possibly as root or
sudo) will do the steps above.
Disassembler Example
--------------------
The cross-version disassembler that is packaged here, can produce
assembly listing that are superior to those typically found in
Python's dis module. Here is an example::
pydisasm --show-source -F extended bytecode_3.8/pydisasm-example.pyc
byte-compiling simple_source/pydisasm-example.py to bytecode_3.8/pydisasm-example.py.pyc
/src/external-vcs/github/rocky/python-xdis/test
# pydisasm version 6.1.0.dev0
# Python bytecode 3.8.0 (3413)
# Disassembled from Python 3.8.17 (default, Jun 21 2023, 08:20:16)
# [GCC 12.2.0]
# Timestamp in code: 1693155156 (2023-08-27 12:52:36)
# Source code size mod 2**32: 320 bytes
# Method Name: <module>
# Filename: simple_source/pydisasm-example.py
# Argument count: 0
# Position-only argument count: 0
# Keyword-only arguments: 0
# Number of locals: 0
# Stack size: 3
# Flags: 0x00000040 (NOFREE)
# First Line: 4
# Constants:
# 0: 0
# 1: None
# 2: ('version_info',)
# 3: 1
# 4: (2, 4)
# 5: 'Is small power of two'
# Names:
# 0: sys
# 1: version_info
# 2: print
# 3: version
# 4: len
# 5: major
# 6: power_of_two
# import sys
4: 0 LOAD_CONST (0)
2 LOAD_CONST (None)
4 IMPORT_NAME (sys)
6 STORE_NAME (sys) | sys = import(sys)
# from sys import version_info
5: 8 LOAD_CONST (0)
10 LOAD_CONST (('version_info',))
12 IMPORT_NAME (sys)
14 IMPORT_FROM (version_info)
16 STORE_NAME (version_info) | version_info = import(version_info)
18 POP_TOP
# print(sys.version)
7: 20 LOAD_NAME (print)
22 LOAD_NAME (sys)
24 LOAD_ATTR (version) | sys.version
26 CALL_FUNCTION (1 positional argument) | print(sys.version)
28 POP_TOP
# print(len(version_info))
8: 30 LOAD_NAME (print)
32 LOAD_NAME (len)
34 LOAD_NAME (version_info)
36 CALL_FUNCTION (1 positional argument) | len(version_info)
38 CALL_FUNCTION (1 positional argument) | print(len(version_info))
40 POP_TOP
# major = sys.version_info[0]
9: 42 LOAD_NAME (sys)
44 LOAD_ATTR (version_info) | sys.version_info
46 LOAD_CONST (0)
48 BINARY_SUBSCR sys.version_info[0]
50 STORE_NAME (major) | major = sys.version_info[0]
# power_of_two = major & (major - 1)
10: 52 LOAD_NAME (major)
54 LOAD_NAME (major)
56 LOAD_CONST (1)
58 BINARY_SUBTRACT major - 1
60 BINARY_AND major & (major - 1)
62 STORE_NAME (power_of_two) | power_of_two = major & (major - 1)
# if power_of_two in (2, 4):
11: 64 LOAD_NAME (power_of_two)
66 LOAD_CONST ((2, 4))
68 COMPARE_OP (in) | power_of_two in (2, 4)
70 POP_JUMP_IF_FALSE (to 80)
# print("Is small power of two")
12: 72 LOAD_NAME (print)
74 LOAD_CONST ('Is small power of two')
76 CALL_FUNCTION (1 positional argument) | print('Is small power of two')
78 POP_TOP
>> 80 LOAD_CONST (None)
82 RETURN_VALUE return None
Note in the above that some operand interpretation is done on items that are in the stack.
For example in ::
24 LOAD_ATTR (version) | sys.version
from the instruction see that ``sys.version`` is the resolved attribute that is loaded.
Similarly in::
68 COMPARE_OP (in) | power_of_two in (2, 4)
we see that we can resolve the two arguments of the ``in`` operation.
Finally in some ``CALL_FUNCTIONS`` we can figure out the name of the function and arguments passed to it.
Testing
-------
::
$ make check
A GNU makefile has been added to smooth over setting running the right
command, and running tests from fastest to slowest.
If you have remake_ installed, you can see the list of all tasks
including tests via ``remake --tasks``.
Usage
-----
Run
::
$ ./bin/pydisasm -h
for usage help.
As a drop-in replacement for dis
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`xdis` also provides some support as a drop in replacement for the
the Python library `dis <https://docs.python.org/3/library/dis.html>`_
module. This is may be desirable when you want to use the improved API
from Python 3.4 or later from an earlier Python version.
For example:
>>> # works in Python 2 and 3
>>> import xdis.std as dis
>>> [x.opname for x in dis.Bytecode('a = 10')]
['LOAD_CONST', 'STORE_NAME', 'LOAD_CONST', 'RETURN_VALUE']
There may some small differences in output produced for formatted
disassembly or how we show compiler flags. We expect you'll
find the ``xdis`` output more informative though.
See Also
--------
* https://pypi.org/project/uncompyle6/ : Python Bytecode Deparsing
* https://pypi.org/project/decompyle3/ : Python Bytecode Deparsing for Python 3.7 and 3.8
* https://pypi.org/project/xasm/ : Python Bytecode Assembler
* https://pypi.org/project/x-python/ : Python Bytecode Interpreter written in Python
.. _trepan: https://pypi.python.org/pypi/trepan
.. _debuggers: https://pypi.python.org/pypi/trepan3k
.. _remake: http://bashdb.sf.net/remake
.. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/xdis.svg
.. |Latest Version| image:: https://badge.fury.io/py/xdis.svg :target: https://badge.fury.io/py/xdis
.. |PyPI Installs| image:: https://pepy.tech/badge/xdis/month
.. |packagestatus| image:: https://repology.org/badge/vertical-allrepos/python:xdis.svg :target: https://repology.org/project/python:xdis/versions
.. _dis: https://docs.python.org/3/library/dis.html
Raw data
{
"_id": null,
"home_page": "https://github.com/rocky/python-xdis/",
"name": "xdis",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Rocky Bernstein, Hartmut Goebel and others",
"author_email": "rb@dustyfeet.com",
"download_url": "https://files.pythonhosted.org/packages/c3/0f/7a8871aa13b49291acc7193399d57d7d44f668370c6625e0c794138b789b/xdis-6.1.0.tar.gz",
"platform": null,
"description": "|PyPI Installs| |Latest Version| |Supported Python Versions|\n\n|packagestatus|\n\nxdis\n====\n\nA Cross-Python bytecode disassembler, bytecode/wordcode and magic-number manipulation library/package.\n\n\nIntroduction\n------------\n\nThe Python dis_ module allows you to disassemble bytecode from the same\nversion of Python that you are running on. But what about bytecode from\ndifferent versions?\n\nThat's what this package is for. It can \"marshal load\" Python\nbytecodes from different versions of Python. The command-line routine\n*pydisasm* will show disassembly output using the most modern Python\ndisassembly conventions in a variety of user-specified formats. Some\nof these formats like `extended` and `extended-format` are the most\nadvanced of any Python disassembler I know of because they can show\nexpression-tree on operators. See the [Disasembler\nExample][#disasembler-example] below.\n\nAlso, if you need to modify and write bytecode, the routines here can\nbe of help. There are routines to pack and unpack the read-only tuples\nin Python's Code type. For interoperability between Python 2 and 3 we\nprovide our own versions of the Code type, and we provide routines to\nreduce the tedium in writing a bytecode file.\n\nThis package also has an extensive knowledge of Python bytecode magic\nnumbers, including Pypy and others, and how to translate from\n``sys.sys_info`` major, minor, and release numbers to the corresponding\nmagic value.\n\nSo if you want to write a cross-version assembler, or a\nbytecode-level optimizer this package may also be useful. In addition\nto the kinds of instruction categorization that ``dis``` offers, we have\nadditional categories for things that would be useful in such a\nbytecode assembler, optimizer, or decompiler.\n\nThe programs here accept bytecodes from Python version 1.0 to 3.11 or\nso. The code requires Python 2.4 or later and has been tested on\nPython running lots of Python versions.\n\nWhen installing, except for the most recent versions of Python, use\nthe Python egg or wheel that matches that version, e.g. ``xdis-6.0.2-py3.3.egg``, ``xdis-6.0.2-py33-none-any.whl``.\nOf course for versions that pre-date wheel's, like Python 2.6, you will have to use eggs.\n\nTo install older versions for from source in git use the branch\n``python-2.4-to-2.7`` for Python versions from 2.4 to 2.7,\n``python-3.1-to-3.2`` for Python versions from 3.1 to 3.2,\n``python-3.3-to-3.5`` for Python versions from 3.3 to 3.5. The master\nbranch handles Python 3.6 and later.\n\nInstallation\n------------\n\nThe standard Python routine:\n\n::\n\n $ pip install -e .\n $ pip install -r requirements-dev.txt\n\nA GNU makefile is also provided so ``make install`` (possibly as root or\nsudo) will do the steps above.\n\nDisassembler Example\n--------------------\n\nThe cross-version disassembler that is packaged here, can produce\nassembly listing that are superior to those typically found in\nPython's dis module. Here is an example::\n\n pydisasm --show-source -F extended bytecode_3.8/pydisasm-example.pyc\n byte-compiling simple_source/pydisasm-example.py to bytecode_3.8/pydisasm-example.py.pyc\n /src/external-vcs/github/rocky/python-xdis/test\n # pydisasm version 6.1.0.dev0\n # Python bytecode 3.8.0 (3413)\n # Disassembled from Python 3.8.17 (default, Jun 21 2023, 08:20:16)\n # [GCC 12.2.0]\n # Timestamp in code: 1693155156 (2023-08-27 12:52:36)\n # Source code size mod 2**32: 320 bytes\n # Method Name: <module>\n # Filename: simple_source/pydisasm-example.py\n # Argument count: 0\n # Position-only argument count: 0\n # Keyword-only arguments: 0\n # Number of locals: 0\n # Stack size: 3\n # Flags: 0x00000040 (NOFREE)\n # First Line: 4\n # Constants:\n # 0: 0\n # 1: None\n # 2: ('version_info',)\n # 3: 1\n # 4: (2, 4)\n # 5: 'Is small power of two'\n # Names:\n # 0: sys\n # 1: version_info\n # 2: print\n # 3: version\n # 4: len\n # 5: major\n # 6: power_of_two\n # import sys\n 4: 0 LOAD_CONST (0)\n 2 LOAD_CONST (None)\n 4 IMPORT_NAME (sys)\n 6 STORE_NAME (sys) | sys = import(sys)\n\n # from sys import version_info\n 5: 8 LOAD_CONST (0)\n 10 LOAD_CONST (('version_info',))\n 12 IMPORT_NAME (sys)\n 14 IMPORT_FROM (version_info)\n 16 STORE_NAME (version_info) | version_info = import(version_info)\n 18 POP_TOP\n\n # print(sys.version)\n 7: 20 LOAD_NAME (print)\n 22 LOAD_NAME (sys)\n 24 LOAD_ATTR (version) | sys.version\n 26 CALL_FUNCTION (1 positional argument) | print(sys.version)\n 28 POP_TOP\n\n # print(len(version_info))\n 8: 30 LOAD_NAME (print)\n 32 LOAD_NAME (len)\n 34 LOAD_NAME (version_info)\n 36 CALL_FUNCTION (1 positional argument) | len(version_info)\n 38 CALL_FUNCTION (1 positional argument) | print(len(version_info))\n 40 POP_TOP\n\n # major = sys.version_info[0]\n 9: 42 LOAD_NAME (sys)\n 44 LOAD_ATTR (version_info) | sys.version_info\n 46 LOAD_CONST (0)\n 48 BINARY_SUBSCR sys.version_info[0]\n 50 STORE_NAME (major) | major = sys.version_info[0]\n\n # power_of_two = major & (major - 1)\n 10: 52 LOAD_NAME (major)\n 54 LOAD_NAME (major)\n 56 LOAD_CONST (1)\n 58 BINARY_SUBTRACT major - 1\n 60 BINARY_AND major & (major - 1)\n 62 STORE_NAME (power_of_two) | power_of_two = major & (major - 1)\n\n # if power_of_two in (2, 4):\n 11: 64 LOAD_NAME (power_of_two)\n 66 LOAD_CONST ((2, 4))\n 68 COMPARE_OP (in) | power_of_two in (2, 4)\n 70 POP_JUMP_IF_FALSE (to 80)\n\n # print(\"Is small power of two\")\n 12: 72 LOAD_NAME (print)\n 74 LOAD_CONST ('Is small power of two')\n 76 CALL_FUNCTION (1 positional argument) | print('Is small power of two')\n 78 POP_TOP\n >> 80 LOAD_CONST (None)\n 82 RETURN_VALUE return None\n\nNote in the above that some operand interpretation is done on items that are in the stack.\nFor example in ::\n\n 24 LOAD_ATTR (version) | sys.version\n\nfrom the instruction see that ``sys.version`` is the resolved attribute that is loaded.\n\nSimilarly in::\n\n 68 COMPARE_OP (in) | power_of_two in (2, 4)\n\nwe see that we can resolve the two arguments of the ``in`` operation.\nFinally in some ``CALL_FUNCTIONS`` we can figure out the name of the function and arguments passed to it.\n\n\n\nTesting\n-------\n\n::\n\n $ make check\n\nA GNU makefile has been added to smooth over setting running the right\ncommand, and running tests from fastest to slowest.\n\nIf you have remake_ installed, you can see the list of all tasks\nincluding tests via ``remake --tasks``.\n\n\nUsage\n-----\n\nRun\n\n::\n\n $ ./bin/pydisasm -h\n\nfor usage help.\n\n\nAs a drop-in replacement for dis\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n`xdis` also provides some support as a drop in replacement for the\nthe Python library `dis <https://docs.python.org/3/library/dis.html>`_\nmodule. This is may be desirable when you want to use the improved API\nfrom Python 3.4 or later from an earlier Python version.\n\nFor example:\n\n>>> # works in Python 2 and 3\n>>> import xdis.std as dis\n>>> [x.opname for x in dis.Bytecode('a = 10')]\n['LOAD_CONST', 'STORE_NAME', 'LOAD_CONST', 'RETURN_VALUE']\n\nThere may some small differences in output produced for formatted\ndisassembly or how we show compiler flags. We expect you'll\nfind the ``xdis`` output more informative though.\n\nSee Also\n--------\n\n* https://pypi.org/project/uncompyle6/ : Python Bytecode Deparsing\n* https://pypi.org/project/decompyle3/ : Python Bytecode Deparsing for Python 3.7 and 3.8\n* https://pypi.org/project/xasm/ : Python Bytecode Assembler\n* https://pypi.org/project/x-python/ : Python Bytecode Interpreter written in Python\n\n.. _trepan: https://pypi.python.org/pypi/trepan\n.. _debuggers: https://pypi.python.org/pypi/trepan3k\n.. _remake: http://bashdb.sf.net/remake\n.. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/xdis.svg\n.. |Latest Version| image:: https://badge.fury.io/py/xdis.svg :target: https://badge.fury.io/py/xdis\n.. |PyPI Installs| image:: https://pepy.tech/badge/xdis/month\n.. |packagestatus| image:: https://repology.org/badge/vertical-allrepos/python:xdis.svg :target: https://repology.org/project/python:xdis/versions\n.. _dis: https://docs.python.org/3/library/dis.html\n\n\n\n",
"bugtrack_url": null,
"license": "GPL-2.0",
"summary": "Python cross-version byte-code disassembler and marshal routines",
"version": "6.1.0",
"project_urls": {
"Homepage": "https://github.com/rocky/python-xdis/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0126822e7ffd806eb889ef7c90b1538ac57144f5b04885e226f9ed9f8fa5f3d0",
"md5": "cf07e539948970b93f522778f2a064d9",
"sha256": "78efc7c7c598a8704e99a58bc1ac974361e1df6d751e2d9f4ef25c787bec525e"
},
"downloads": -1,
"filename": "xdis-6.1.0-py2-none-any.whl",
"has_sig": false,
"md5_digest": "cf07e539948970b93f522778f2a064d9",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": null,
"size": 182527,
"upload_time": "2024-03-16T01:19:13",
"upload_time_iso_8601": "2024-03-16T01:19:13.011088Z",
"url": "https://files.pythonhosted.org/packages/01/26/822e7ffd806eb889ef7c90b1538ac57144f5b04885e226f9ed9f8fa5f3d0/xdis-6.1.0-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9a8c3430daf90c3f2c791d145f05d5928878406b04b0c5e367eb87461112f9d",
"md5": "f1bb909e5b61c8732ef87e68125c100a",
"sha256": "aa9954c1aa2bde974ee620a23a100b63a46113abdbb703b97c3f11b7f5873db8"
},
"downloads": -1,
"filename": "xdis-6.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f1bb909e5b61c8732ef87e68125c100a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 169184,
"upload_time": "2024-03-16T01:34:29",
"upload_time_iso_8601": "2024-03-16T01:34:29.226224Z",
"url": "https://files.pythonhosted.org/packages/b9/a8/c3430daf90c3f2c791d145f05d5928878406b04b0c5e367eb87461112f9d/xdis-6.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c30f7a8871aa13b49291acc7193399d57d7d44f668370c6625e0c794138b789b",
"md5": "0b40258622076781454267a8feb9244d",
"sha256": "355fd36db210e9117167e0821e2bcc12ac3da8bcc15d52e1542ad422ad2629cc"
},
"downloads": -1,
"filename": "xdis-6.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0b40258622076781454267a8feb9244d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 401813,
"upload_time": "2024-03-16T01:22:47",
"upload_time_iso_8601": "2024-03-16T01:22:47.213959Z",
"url": "https://files.pythonhosted.org/packages/c3/0f/7a8871aa13b49291acc7193399d57d7d44f668370c6625e0c794138b789b/xdis-6.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 01:22:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rocky",
"github_project": "python-xdis",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"circle": true,
"requirements": [],
"tox": true,
"lcname": "xdis"
}
JSON
