Some people have mistaken Python bytecode as being stable and unchanging. In

reality it's simply an implementation detail for CPython. This point is now
clearly documented in both the docs for dis and the glossary.

Closes issue #7829. Thanks to Terry Reedy for some initial suggestions on
wording.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 8363714583ee9fdec4419da43979c856e61f03f9..98744eb18c53714b712b5325d0d64a2ac5fbfc27 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -57,11 +57,14 @@ Glossary
 
    bytecode
       Python source code is compiled into bytecode, the internal representation
-      of a Python program in the interpreter.  The bytecode is also cached in
-      ``.pyc`` and ``.pyo`` files so that executing the same file is faster the
-      second time (recompilation from source to bytecode can be avoided).  This
-      "intermediate language" is said to run on a :term:`virtual machine`
-      that executes the machine code corresponding to each bytecode.
+      of a Python program in the CPython interpreter.  The bytecode is also
+      cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
+      faster the second time (recompilation from source to bytecode can be
+      avoided).  This "intermediate language" is said to run on a
+      :term:`virtual machine` that executes the machine code corresponding to
+      each bytecode. Do note that bytecodes are not expected to work between
+      different Python virtual machines, nor to be stable between Python
+      releases.
 
    class
       A template for creating user-defined objects. Class definitions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index b62a6731ace0dd13c196f3857661b8c7fbefb1c8..c9417ead407090b8c78938d503e8dbd926429108 100644 (file)
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -5,12 +5,13 @@
    :synopsis: Disassembler for Python bytecode.
 
 
-The :mod:`dis` module supports the analysis of Python :term:`bytecode` by
-disassembling it.  Since there is no Python assembler, this module defines the
-Python assembly language.  The Python bytecode which this module takes as an
+The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
+disassembling it. The CPython bytecode which this module takes as an
 input is defined in the file :file:`Include/opcode.h` and used by the compiler
 and the interpreter.
 
+.. warning:: Bytecode is an implementation detail of the CPython interpreter!  No guarantees are made that bytecode will not be added, removed, or changed between versions of Python. Use of this module should not be considered to work across Python VMs or Python releases.
+
 Example: Given the function :func:`myfunc`::
 
    def myfunc(alist):

diff --git a/Misc/NEWS b/Misc/NEWS
index 94de1714d3c4f2be6eab8552fcb88013be404771..403c73137e9fb27ab216f84d90d83aefc3fc0eeb 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -468,6 +468,9 @@ C-API
 Library
 -------
 
+- Issue #7829: Clearly document that the dis module is exposing an
+  implementation detail that is not stable between Python VMs or releases.
+
 - Issue #6589: cleanup asyncore.socket_map in case smtpd.SMTPServer constructor 
   raises an exception.