Better docs explaining import _imaging failure [ci skip]

PIL/Image.py

@@ -55,10 +55,11 @@ except ImportError:
     pass
 
 try:
-    # If the _imaging C module is not present, you can still use
+    # If the _imaging C module is not present, Pillow will not load.
-    # the "open" function to identify files, but you cannot load
+    # Note that other modules should not refer to _imaging directly;
-    # them.  Note that other modules should not refer to _imaging
+    # import Image and use the Image.core variable instead.
-    # directly; import Image and use the Image.core variable instead.
+    # Also note that Image.core is not a publicly documented interface,
+    # and should be considered private and subject to change. 
     from PIL import _imaging as core
     if PILLOW_VERSION != getattr(core, 'PILLOW_VERSION', None):
         raise ImportError("The _imaging extension was built for another "
@@ -91,6 +92,7 @@ except ImportError as v:
             RuntimeWarning
             )
     # Fail here anyway. Don't let people run with a mostly broken Pillow.
+    # see docs/porting-pil-to-pillow.rst
     raise
 
 try:

docs/porting-pil-to-pillow.rst

@@ -21,3 +21,7 @@ automatically imports any file in the Python path with a name ending
 in :file:`ImagePlugin.py`. You will need to import your image plugin
 manually.
 
+Pillow will raise an exception if the core extension can't be loaded
+for any reason, including a version mismatch between the Python and
+extension code. Previously PIL allowed Python only code to run if the
+core extension was not available.