PEP 511: add usages to the rationale

pep-0511.txt

@@ -30,8 +30,14 @@ hook its AST transformer. Another option is to monkey-patch the
 builtin ``compile()`` function. There are even more options to
 hook a code transformer.
 
-Transforming the code allows to extend the Python language for specific
-use cases. Transforming an Abstract Syntax Tree (AST) is a convenient
+Python 3.4 added a ``compile_source()`` method to
+``importlib.abc.SourceLoader``. But code transformation is wider than just
+importing modules, see described use cases below.
+
+Usage 1: AST optimizer
+----------------------
+
+Transforming an Abstract Syntax Tree (AST) is a convenient
 way to implement an optimizer. It's easier to work on the AST than
 working on the bytecode, AST contains more information and is more high
 level.
@@ -41,17 +47,29 @@ definition, a peephole optimizer has a narrow view of the code and so
 can only implement basic optimizations. The optimizer rewrites the
 bytecode. It is difficult to enhance it, because it written in C.
 
-This PEP proposes to add an API to register AST transformers.
+Usage 2: Preprocessor
+---------------------
 
-A new ``-o OPTIM_TAG`` command line option is added to only load
-transformed code: it changes the name of searched ``.pyc`` files. If the
-``.pyc`` file of a module is missing and the ``.py`` is available, an
-``ImportError`` exception is raised import if the AST transformers
-required to transform the code are missing. The import behaviour with
-the default optimizer tag (``'opt'``) is unchanged.
+A preprocessor can be easily implemented with an AST transformer. A
+preprocessor has various and different usages. Examples:
 
-The transformation can done ahead of time. It allows to implement
-powerful but expensive transformations.
+* Remove debug code (like assertions and logs) to make the code faster to run
+  it for production.
+* `Tail-call Optimization <https://en.wikipedia.org/wiki/Tail_call>`_
+* Add profiling code
+* Lazy macro create a memoizing thunk.
+
+Examples extending or changing the Python language:
+
+* Domain Specific Language (DSL) like SQL queries. The
+  Python language itself doesn't need to be modified. Previous attempts to
+  implement DSL for SQL like `PEP 335 - Overloadable Boolean Operators
+  <https://www.python.org/dev/peps/pep-0335/>`_ was rejected.
+* Pattern Matching of functional languages
+* String Interpolation, but `PEP 498 -- Literal String Interpolation
+  <https://www.python.org/dev/peps/pep-0498/>`_ was merged into Python 3.6.
+
+MacroPy has a much longer list of examples and use cases.
 
 
 Use Cases
@@ -127,6 +145,18 @@ available.
 Changes
 =======
 
+This PEP proposes to add an API to register AST transformers.
+
+A new ``-o OPTIM_TAG`` command line option is added to only load
+transformed code: it changes the name of searched ``.pyc`` files. If the
+``.pyc`` file of a module is missing and the ``.py`` is available, an
+``ImportError`` exception is raised import if the AST transformers
+required to transform the code are missing. The import behaviour with
+the default optimizer tag (``'opt'``) is unchanged.
+
+The transformation can done ahead of time. It allows to implement
+powerful but expensive transformations.
+
 API to support AST transformers:
 
 * Add ``sys.ast_transformers``: list of AST transformers used to rewrite