[Python-checkins] cpython: Issue #18192: Introduce importlib.util.MAGIC_NUMBER and document the

[brett.cannon]

http://hg.python.org/cpython/rev/5619bc2d8207
changeset:   84128:5619bc2d8207
user:        Brett Cannon <brett at python.org>
date:        Fri Jun 14 19:02:34 2013 -0400
summary:
  Issue #18192: Introduce importlib.util.MAGIC_NUMBER and document the
deprecation of imp.get_magic().

files:
  Doc/library/imp.rst                  |   3 +++
  Doc/library/importlib.rst            |   7 +++++++
  Lib/imp.py                           |   8 ++++++--
  Lib/importlib/_bootstrap.py          |   8 ++++----
  Lib/importlib/util.py                |   1 +
  Lib/test/test_importlib/test_util.py |  11 +++++++++++
  Misc/NEWS                            |   3 +++
  Python/importlib.h                   |   4 ++--
  8 files changed, 37 insertions(+), 8 deletions(-)


diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -21,6 +21,9 @@
    Return the magic string value used to recognize byte-compiled code files
    (:file:`.pyc` files).  (This value may be different for each Python version.)
 
+   .. deprecated:: 3.4
+       Use :attr:`importlib.util.MAGIC_NUMBER` instead.
+
 
 .. function:: get_suffixes()
 
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -879,6 +879,13 @@
 This module contains the various objects that help in the construction of
 an :term:`importer`.
 
+.. attribute:: MAGIC_NUMBER
+
+   The bytes which represent the bytecode version number. If you need help with
+   loading/writing bytecode then consider :class:`importlib.abc.SourceLoader`.
+
+   .. versionadded:: 3.4
+
 .. function:: resolve_name(name, package)
 
    Resolve a relative module name to an absolute one.
diff --git a/Lib/imp.py b/Lib/imp.py
--- a/Lib/imp.py
+++ b/Lib/imp.py
@@ -23,6 +23,7 @@
 
 from importlib import _bootstrap
 from importlib import machinery
+from importlib import util
 import importlib
 import os
 import sys
@@ -44,8 +45,11 @@
 
 
 def get_magic():
-    """Return the magic number for .pyc or .pyo files."""
-    return _bootstrap._MAGIC_BYTES
+    """**DEPRECATED**
+
+    Return the magic number for .pyc or .pyo files.
+    """
+    return util.MAGIC_NUMBER
 
 
 def get_tag():
diff --git a/Lib/importlib/_bootstrap.py b/Lib/importlib/_bootstrap.py
--- a/Lib/importlib/_bootstrap.py
+++ b/Lib/importlib/_bootstrap.py
@@ -383,8 +383,8 @@
 # longer be understood by older implementations of the eval loop (usually
 # due to the addition of new opcodes).
 
-_MAGIC_BYTES = (3280).to_bytes(2, 'little') + b'\r\n'
-_RAW_MAGIC_NUMBER = int.from_bytes(_MAGIC_BYTES, 'little')  # For import.c
+MAGIC_NUMBER = (3280).to_bytes(2, 'little') + b'\r\n'
+_RAW_MAGIC_NUMBER = int.from_bytes(MAGIC_NUMBER, 'little')  # For import.c
 
 _PYCACHE = '__pycache__'
 
@@ -663,7 +663,7 @@
     magic = data[:4]
     raw_timestamp = data[4:8]
     raw_size = data[8:12]
-    if magic != _MAGIC_BYTES:
+    if magic != MAGIC_NUMBER:
         message = 'bad magic number in {!r}: {!r}'.format(name, magic)
         _verbose_message(message)
         raise ImportError(message, **exc_details)
@@ -711,7 +711,7 @@
 def _code_to_bytecode(code, mtime=0, source_size=0):
     """Compile a code object into bytecode for writing out to a byte-compiled
     file."""
-    data = bytearray(_MAGIC_BYTES)
+    data = bytearray(MAGIC_NUMBER)
     data.extend(_w_long(mtime))
     data.extend(_w_long(source_size))
     data.extend(marshal.dumps(code))
diff --git a/Lib/importlib/util.py b/Lib/importlib/util.py
--- a/Lib/importlib/util.py
+++ b/Lib/importlib/util.py
@@ -1,5 +1,6 @@
 """Utility code for constructing importers, etc."""
 
+from ._bootstrap import MAGIC_NUMBER
 from ._bootstrap import module_to_load
 from ._bootstrap import set_loader
 from ._bootstrap import set_package
diff --git a/Lib/test/test_importlib/test_util.py b/Lib/test/test_importlib/test_util.py
--- a/Lib/test/test_importlib/test_util.py
+++ b/Lib/test/test_importlib/test_util.py
@@ -313,5 +313,16 @@
             util.resolve_name('..bacon', 'spam')
 
 
+class MagicNumberTests(unittest.TestCase):
+
+    def test_length(self):
+        # Should be 4 bytes.
+        self.assertEqual(len(util.MAGIC_NUMBER), 4)
+
+    def test_incorporates_rn(self):
+        # The magic number uses \r\n to come out wrong when splitting on lines.
+        self.assertTrue(util.MAGIC_NUMBER.endswith(b'\r\n'))
+
+
 if __name__ == '__main__':
     unittest.main()
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -123,6 +123,9 @@
 Library
 -------
 
+- Issue #18192: Introduce importlib.util.MAGIC_NUMBER and document as deprecated
+  imp.get_magic().
+
 - Issue #18149: Add filecmp.clear_cache() to manually clear the filecmp cache.
   Patch by Mark Levitt
 
diff --git a/Python/importlib.h b/Python/importlib.h
--- a/Python/importlib.h
+++ b/Python/importlib.h
[stripped]

-- 
Repository URL: http://hg.python.org/cpython