Merge pull request #651 from bsolomon1124/binary-ext-use-case-examples

Binary extension use cases: provide examples

source/guides/packaging-binary-extensions.rst

@@ -25,25 +25,33 @@ Use cases
 The typical use cases for binary extensions break down into just three
 conventional categories:
 
-* accelerator modules: these modules are completely self-contained, and
+* **accelerator modules**: these modules are completely self-contained, and
   are created solely to run faster than the equivalent pure Python code
   runs in CPython. Ideally, accelerator modules will always have a pure
   Python equivalent to use as a fallback if the accelerated version isn't
   available on a given system. The CPython standard library makes extensive
   use of accelerator modules.
-
-* wrapper modules: these modules are created to expose existing C interfaces
+  *Example*: When importing ``datetime``, Python falls back to the
+  `datetime.py <https://github.com/python/cpython/blob/master/Lib/datetime.py>`_
+  module if the C implementation (
+  `_datetimemodule.c <https://github.com/python/cpython/blob/master/Modules/_datetimemodule.c>`_)
+  is not available.
+* **wrapper modules**: these modules are created to expose existing C interfaces
   to Python code. They may either expose the underlying C interface directly,
   or else expose a more "Pythonic" API that makes use of Python language
   features to make the API easier to use. The CPython standard library makes
   extensive use of wrapper modules.
-
-* low level system access: these modules are created to access lower level
+  *Example*: `functools.py <https://github.com/python/cpython/blob/master/Lib/functools.py>`_
+  is a Python module wrapper for
+  `_functoolsmodule.c <https://github.com/python/cpython/blob/master/Modules/_functoolsmodule.c>`_.
+* **low-level system access**: these modules are created to access lower level
   features of the CPython runtime, the operating system, or the underlying
   hardware. Through platform specific code, extension modules may achieve
   things that aren't possible in pure Python code. A number of CPython
   standard library modules are written in C in order to access interpreter
   internals that aren't exposed at the language level.
+  *Example*: ``sys``, which comes from
+  `sysmodule.c <https://github.com/python/cpython/blob/master/Python/sysmodule.c>`_.
 
   One particularly notable feature of C extensions is that, when they don't
   need to call back into the interpreter runtime, they can release CPython's