Documentation for using xdis as a library?

[bjpop]

Description

Is there any API documentation for xdis? If not it would be useful to provide some information about how to use it as a library.

Background

I looked for API documentation but couldn't find any. Apologies in advance if I missed something obvious.

[rocky]

The README says you can use it as a drop-in replacement for dis. So use your favorite API documentation for Python's dis. Basically the only difference is that many functions allow for an optional version tuple. https://libraries.io/pypi/xdis lists packages that use xdis so you can look at one of those to see that.

Finally, since this is open-source, feel free to contribute whatever kind of API documentation you feel most helpful. Or provide the kind of documentation that you are/were hoping to see.

[bjpop]

Thanks @rocky

I was hoping to use xdis for constructing new code objects from byte code instructions, essentially the inverse functionality of dis (where dis lets you take a Python object and get back the bytecode).

I'm looking for something that will make it easy for me to do some transformations on the bytecode and then turn the result back into a Python object that can be executed.

I don't think this can be done with dis.

Therefore I went searching for something that could do this, and xdis was mentioned in a Stack Overflow comment.

Is this functionality provided by xdis? If not do you happen to know something that can do what I described?

Of course I could roll my own but I'd rather use something that someone else has built and tested etc.

[bjpop]

Looking at your other projects, it seems like I should be using python-xasm instead?

[rocky]

I was hoping to use xdis for constructing new code objects from byte code instructions, essentially the inverse functionality of dis (where dis lets you take a Python object and get back the bytecode).
I don't think this can be done with dis.

You are correct. It can't be done with dis or, more generally, any disassembler.

Looking at your other projects, it seems like I should be using python-xasm instead?

Possibly. But to set expectations a little. You can't just take any arbitrary sequence of bytecode instructions, even if it comes from valid Python and expect to get back a code object. Code objects exist for things that correspond to single statements, lambdas, comprehension bodies, or expressions from Python source code that can be eval'd.

So for example the single bytecode instruction ADD x should not be turned into a code object, even if you manage technically to do it. Because, if for no other reason that it pulls a value on the evaluation stack that should have been added previously.

Code objects then have additional information such as a list of local variables and max stack depth entries and other stuff. That would need to get filled in from somewhere.

Second, given you stick to the limitations set forth, python-xasm might help - but now you'll need to provide input to that the meets the kind of thing set out above. Personally, the easiest way way to feed something into xasm is via using xdis rather than dis because xdis has an output format that allows for a little bit of abstraction into a generic instruction from one that is specific for a particular section of a code object. In particular, jump offsets may need to be adjusted. Mapping from numbers to local variables may need adjusting too.

Third, xasm isn't used that much, at least not by me, and the whole topic is fraught with caveats. For example xasm isn't going to detect stack overflow or underflow when given instructions that can do this.

Anyway this is getting a little long. And it really isn't an xdis issue, so I am closing this.