Add hints and descriptions for building C API.

Author: fangerer

README.md

@@ -32,6 +32,41 @@ source <dir-to-venv>/bin/activate
 
 In the venv multiple executables are available, like `python`, `python3` and `graalpython`. 
 
+### Using modules with C extensions
+
+This Python implementation is able to load and run modules with C extensions.
+Supporting C extensions is one of the most difficult features for any Python 
+implementation since it requires to be compatible to CPython's C API.
+
+However, GraalVM's Python implementation is capable of executing C extensions and
+there is also no optimization boundary.
+
+In order to be able to run C extensions, a user must first build the C API
+runtime library. It is recommended to build the C API in any case because
+it will only be used if necessary. 
+The recommended way to do so is to create a venv (see [Create a virtual environment](#create-a-virtual-environment))
+and run everything within the venv.
+
+If you don't want to create and use a venv, the C API can be built using
+following command:
+```
+mx python -m build_capi
+```
+
+You can test if everything was built correctly by, for example, using 
+a memoryvew object:
+```
+(your-venv) graalpython -c "print(repr(memoryview(b'')))"
+```
+
+in the venv or
+
+```
+mx python -c "print(repr(memoryview(b'')))"
+```
+
+without a venv.
+
 ### Installing packages
 
 At the moment not enough of the standard library is implemented to run the

graalpython/lib-graalpython/_sre.py

@@ -513,7 +513,9 @@ def split(self, string, maxsplit=0):
 _tcompile = SRE_Pattern
 
 def compile(pattern, flags, code, groups, groupindex, indexgroup):
-    import _cpython_sre
+    from build_capi import hint
+    with hint("_cpython_sre"):
+        import _cpython_sre
     return _cpython_sre.compile(pattern, flags, code, groups, groupindex, indexgroup)
 
 
@@ -524,7 +526,9 @@ def getcodesize(*args, **kwargs):
 
 @__builtin__
 def getlower(char_ord, flags):
-    import _cpython_sre
+    from build_capi import hint
+    with hint("_cpython_sre"):
+        import _cpython_sre
     return _cpython_sre.getlower(char_ord, flags)
 
 

graalpython/lib-graalpython/memoryview.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # The Universal Permissive License (UPL), Version 1.0
@@ -45,7 +45,9 @@
 
 
 def __memoryview_init(self, *args, **kwargs):
-    import _memoryview
+    from build_capi import hint
+    with hint("_memoryview"):
+        import _memoryview
     global c_memoryview_module
     c_memoryview_module = _memoryview
     PyTruffle_SetAttr(memoryview, "__init__", __memoryview_init2)

graalpython/lib-graalpython/mmap.py

@@ -54,7 +54,9 @@
 from python_cext import register_capi_hook
 
 def __register_buffer():
-    import _mmap
+    from build_capi import hint
+    with hint("_mmap"):
+        import _mmap
     _mmap.init_bufferprotocol(mmap)
 
 register_capi_hook(__register_buffer)

graalpython/lib-graalpython/unicodedata.py

@@ -45,7 +45,9 @@
 @__builtin__
 def __get_c_unicodedata():
     if c_unicodedata_module is None:
-        import _cpython_unicodedata
+        from build_capi import hint
+        with hint("_cpython_unicodedata"):
+            import _cpython_unicodedata
         global c_unicodedata_module
         c_unicodedata_module = _cpython_unicodedata
     return c_unicodedata_module

graalpython/lib-python/3/build_capi.py

@@ -43,10 +43,10 @@
 import importlib.util
 import distutils.log as dlog
 
+
 capi_home = sys.graal_python_capi_home
 capi_module_home = sys.graal_python_capi_module_home
 
-
 def load_setup():
     spec = importlib.util.spec_from_file_location("setup.py", os.path.join(sys.graal_python_cext_src, "setup.py"))
     setup_module = importlib.util.module_from_spec(spec)
@@ -75,6 +75,24 @@ def clean(args=[]):
     return load_setup().clean(capi_home, capi_module_home)
 
 
+class CapiNotBuiltContextManager:
+    def __init__(self, module_name):
+        self.module_name = module_name
+
+    def __enter__(self):
+        pass
+
+    def __exit__(self, typ, val, tb):
+        if typ and issubclass(typ, ModuleNotFoundError):
+            print("Could not locate module '%s'. Did you forget to build the C API using 'graalpython -m build_capi'?" % self.module_name)
+        # this causes the exception to propagate in any case
+        return False
+
+
+def hint(module_name):
+    return CapiNotBuiltContextManager(module_name)
+
+
 if __name__ == "__main__":
     if "clean" in sys.argv:
         clean(sys.argv)

graalpython/lib-python/3/bz2.py

@@ -16,7 +16,11 @@
 import _compression
 from threading import RLock
 
-from _bz2 import BZ2Compressor, BZ2Decompressor
+# TRUFFLE CHANGE BEGIN
+from build_capi import hint
+with hint("_bz2"):
+    from _bz2 import BZ2Compressor, BZ2Decompressor
+# TRUFFLE CHANGE END
 
 
 _MODE_CLOSED   = 0

graalpython/lib-python/3/struct.py

@@ -17,7 +17,9 @@ def make_delegate(p):
     def delegate(*args ,**kwargs):
         global __cstruct
         if not __cstruct:
-            import _struct as __cstruct
+            from build_capi import hint
+            with hint("_struct"):
+                import _struct as __cstruct
         return getattr(__cstruct, p)(*args, **kwargs)
     delegate.__name__ = p
     return delegate