Add functions to return disassembly as string

[ezio.melotti]

http://bugs.python.org/review/11816/diff/3293/10245
File Doc/library/dis.rst (right):

http://bugs.python.org/review/11816/diff/3293/10245#newcode184
Doc/library/dis.rst:184: as :class:`OpInfo` instances:
If this is a named tuple maybe it should be mentioned here (in addition to or
instead of the mention in the get_opinfo function).

http://bugs.python.org/review/11816/diff/3293/10245#newcode212
Doc/library/dis.rst:212: human readable description of operation argument
An example for each of these would be good (possibly with the same opcode).

http://bugs.python.org/review/11816/diff/3293/10246
File Lib/dis.py (right):

http://bugs.python.org/review/11816/diff/3293/10246#newcode113
Lib/dis.py:113: """Formatted details of methods, functions, or code."""
Should this mention that code might either be str or a code object?

http://bugs.python.org/review/11816/diff/3293/10246#newcode154
Lib/dis.py:154: class OpInfo(_OpInfo):
If this is public it should go in __all__.

http://bugs.python.org/review/11816/diff/3293/10246#newcode272
Lib/dis.py:272: print("%3d" % opinfo.starts_line, end=' ', file=file)
format(opinfo.starts_line, '3d') might be another option

http://bugs.python.org/review/11816/diff/3293/10247
File Lib/test/bytecode_helper.py (right):

http://bugs.python.org/review/11816/diff/3293/10247#newcode35
Lib/test/bytecode_helper.py:35: """Returns opinfo if op is found, otherwise
throws AssertionError"""
From the signature I would expect something like x in opname, where x is some
opcode and opname a disassembled piece of code.  I'm not sure what argval is
supposed to be too.
From the docstring instead, is not clear what opinfo and op are.

http://bugs.python.org/review/11816/diff/3293/10247#newcode39
Lib/test/bytecode_helper.py:39: return opinfo
Is this actually used/useful? assert methods don't return anything, that's also
why assertRaises doesn't return the exception but provides it as an attribute
when used as a context manager.

[rfk]

http://bugs.python.org/review/11816/diff/3293/10247
File Lib/test/bytecode_helper.py (right):

http://bugs.python.org/review/11816/diff/3293/10247#newcode35
Lib/test/bytecode_helper.py:35: """Returns opinfo if op is found, otherwise
throws AssertionError"""
On 2011/09/04 14:42:52, ezio.melotti wrote:
> From the signature I would expect something like x in opname,
> where x is some opcode and opname a disassembled piece of code.
> I'm not sure what argval is supposed to be too.

Yes, it was originally written with only two arguments and in the opposite
order.  By analogy with assertIn(item,seq) -> item in seq, it was
assertInBytecode(opname,code) -> opname in code.

I changed it when I added the optional third argument, so that opname and argval
were together in the signature.

Perhaps calling it something like "assertBytecodeContains" would be better? 
This would avoid the now-confusing similarity to assertIn, and have the nice
side benefit of all bytecode-related assertion methods being
"assertBytecode<SOMETHING>".

[eric.araujo]

Some comments.  Sorry if the tone is sometimes too explain-y, I thought the
patch was by a new contributor, hope you won’t mind.

http://bugs.python.org/review/11816/diff/3349/10434
File Doc/library/dis.rst (right):

http://bugs.python.org/review/11816/diff/3349/10434#newcode172
Doc/library/dis.rst:172: It does *not* include references to global or builtin
scopes).
I’d use a semicolon here to avoid a capital letter inside a parenthese.

http://bugs.python.org/review/11816/diff/3349/10435
File Lib/dis.py (right):

http://bugs.python.org/review/11816/diff/3349/10435#newcode32
Lib/dis.py:32: With no argument, disassemble the last traceback.
Should document the meaning of the file argument.

http://bugs.python.org/review/11816/diff/3349/10435#newcode113
Lib/dis.py:113: """Formatted details of methods, functions, or code."""
Can you improve this docstring so that it mentions the type of the returned
value?

http://bugs.python.org/review/11816/diff/3349/10435#newcode157
Lib/dis.py:157: Defined fields:
This block should be dedented once to the left.

http://bugs.python.org/review/11816/diff/3349/10436
File Lib/test/bytecode_helper.py (right):

http://bugs.python.org/review/11816/diff/3349/10436#newcode1
Lib/test/bytecode_helper.py:1: """bytecode_helper - support tools for testing
correct bytecode generation"""
There is no need to duplicate the name of the module in the docstring, minimally
smart documentation tools will find and display it (see pydoc
test.bytecode_helper for example)

http://bugs.python.org/review/11816/diff/3349/10436#newcode17
Lib/test/bytecode_helper.py:17: def assertBytecodeExactlyMatches(self, x,
expected, *, line_offset=0):
“matches” is associated to regexes in unittest; what about assertBytecodeEqual? 
The unittest comparison machinery can also let you register a comparison
function for bytecode or OpÎnfo objects that is automatically used by
assertEqual.

http://bugs.python.org/review/11816/diff/3349/10436#newcode18
Lib/test/bytecode_helper.py:18: """Throws AssertionError if any discrepancy is
found in bytecode"""
Please use “raise” for exceptions; “throw” is a generator method.

http://bugs.python.org/review/11816/diff/3349/10436#newcode44
Lib/test/bytecode_helper.py:44: msg = '(%s,%r) not found in bytecode:\n%s'
I suggest a space after the comma

[Nick Coghlan]

The "test.bytecode_helper" file is missing from the current patch, but we should
separate out the changes to other tests from from the changes to dis anyway -
only test_dis.py should be altered in this patch.

http://bugs.python.org/review/11816/diff/7359/Doc/library/dis.rst
File Doc/library/dis.rst (right):

http://bugs.python.org/review/11816/diff/7359/Doc/library/dis.rst#newcode64
Doc/library/dis.rst:64: .. versionchanged:: 3.3
With the delay, we also need to bump all these versionadded/versiochanged to 3.4

Something to keep in mind when we add the docs for dis.Bytecode

http://bugs.python.org/review/11816/diff/7359/Doc/whatsnew/3.3.rst
File Doc/whatsnew/3.3.rst (right):

http://bugs.python.org/review/11816/diff/7359/Doc/whatsnew/3.3.rst#newcode873
Doc/whatsnew/3.3.rst:873: (Contributed by Nick Coghlan and Ryan Kelly in
:issue:`11816`)
Similarly, this will need to move to whatsnew/3.4.rst and be updated to ack
Thomas as well.

http://bugs.python.org/review/11816/diff/7359/Lib/dis.py
File Lib/dis.py (right):

http://bugs.python.org/review/11816/diff/7359/Lib/dis.py#newcode379
Lib/dis.py:379: class ByteCode:
Bytecode is one word, so no need for the camel case.

http://bugs.python.org/review/11816/diff/7359/Lib/dis.py#newcode384
Lib/dis.py:384: self.line_offset = 0
This is a good start, but the details reported in the self.info string should
also be available as attributes.

An enhanced repr would also be good. For example, save a ref to the original
object and make __repr__ something like 'return
"{}({!r})".format(self.__class__, repr(x))'

[Thomas Kluyver]

On 2013/02/13 08:03:50, Nick Coghlan wrote:
> http://bugs.python.org/review/11816/diff/7359/Lib/dis.py#newcode384
> Lib/dis.py:384: self.line_offset = 0
> This is a good start, but the details reported in the self.info string should
> also be available as attributes.

They're already attributes on the code object, e.g. as
bytecode.codeobj.co_names. Should we re-expose some or all of them on the
Bytecode object as well? My inclination is that exposing them all again would
make it more confusing, as it wouldn't immediately be obvious that lots of the
available information was simply duplicate references.