bpo-29514: Check magic number for bugfix release (#54)

* bpo-29514: Check magic number for micro release

Add a dict importlib.util.EXPECTED_MAGIC_NUMBERS which
details the initial and expected pyc magic number for
each minor release. This gives a mechanism for users to
check if the magic number has changed within a release and
for a test to ensure procedure is followed if a change is
necessary.

Add a test to check the current MAGIC_NUMBER against the
expected number for the release if the current release is
at candidate or final level. On test failure, describe to
the developer the procedure for changing the magic number.

* Simplify magic number release test

Simplify the magic number release test by removing
EXPECTED_MAGIC_NUMBERS table and making the expected
magic number self-contained within the test.

BPO: 29514

* Improve magic number test execution and message

Improve the execution of the magic number test by
using skipUnless for alpha and beta releases, and
directly inheriting from unittest.TestCase rather than
using the machinery for the other tests. Also improve
the error message to explain the reason for caution in
changing the magic number.

BPO: 29514

Lib/test/test_importlib/test_util.py

@@ -4,6 +4,7 @@ init = util.import_importlib('importlib')
 machinery = util.import_importlib('importlib.machinery')
 importlib_util = util.import_importlib('importlib.util')
 
+import importlib.util
 import os
 import pathlib
 import string
@@ -757,5 +758,48 @@ class PEP3147Tests:
  ) = util.test_both(PEP3147Tests, util=importlib_util)
 
 
+class MagicNumberTests(unittest.TestCase):
+    """
+    Test release compatibility issues relating to importlib
+    """
+    @unittest.skipUnless(
+        sys.version_info.releaselevel in ('final', 'release'),
+        'only applies to candidate or final python release levels'
+    )
+    def test_magic_number(self):
+        """
+        Each python minor release should generally have a MAGIC_NUMBER
+        that does not change once the release reaches candidate status.
+
+        Once a release reaches candidate status, the value of the constant
+        EXPECTED_MAGIC_NUMBER in this test should be changed.
+        This test will then check that the actual MAGIC_NUMBER matches
+        the expected value for the release.
+
+        In exceptional cases, it may be required to change the MAGIC_NUMBER
+        for a maintenance release. In this case the change should be
+        discussed in python-dev. If a change is required, community
+        stakeholders such as OS package maintainers must be notified
+        in advance. Such exceptional releases will then require an
+        adjustment to this test case.
+        """
+        EXPECTED_MAGIC_NUMBER = 3379
+        actual = int.from_bytes(importlib.util.MAGIC_NUMBER[:2], 'little')
+
+        msg = (
+            "To avoid breaking backwards compatibility with cached bytecode "
+            "files that can't be automatically regenerated by the current "
+            "user, candidate and final releases require the current  "
+            "importlib.util.MAGIC_NUMBER to match the expected "
+            "magic number in this test. Set the expected "
+            "magic number in this test to the current MAGIC_NUMBER to "
+            "continue with the release.\n\n"
+            "Changing the MAGIC_NUMBER for a maintenance release "
+            "requires discussion in python-dev and notification of "
+            "community stakeholders."
+        )
+        self.assertEqual(EXPECTED_MAGIC_NUMBER, actual, msg)
+
+
 if __name__ == '__main__':
     unittest.main()