document the peephole optimizer

bytecode/peephole_opt.py

@@ -31,7 +31,7 @@ class ExitUnchanged(Exception):
     pass
 
 
-class _CodePeepholeOptimizer:
+class PeepholeOptimizer:
     """Python reimplementation of the peephole optimizer.
 
     Copy of the C comment:
@@ -466,5 +466,5 @@ class CodeTransformer:
     def code_transformer(self, code, context):
         #print("Optimize %s:%s: %s"
         #      % (code.co_filename, code.co_firstlineno, code.co_name))
-        optimizer = _CodePeepholeOptimizer()
+        optimizer = PeepholeOptimizer()
         return optimizer.optimize(code)

doc/index.rst

@@ -20,6 +20,7 @@ Table Of Contents
 
    usage
    api
+   peephole
    changelog
 
 

doc/peephole.rst

@@ -0,0 +1,79 @@
+******************
+Peephole Optimizer
+******************
+
+Peephole optimizer based on the peephole optimizer of CPython 3.6 written in C.
+
+It is implemented with the :class:`BytecodeBlocks` class.
+
+
+Optimizations
+=============
+
+Optimizations implemented in the peephole optimizer:
+
+* Constant folding
+
+  - unary operations: +a, -a, ~a
+  - binary operations:
+
+    * a + b, a - b, a * b, a / b, a // b, a % b, a ** b
+    * a << b, a >> b, a & b, a | b, a ^ b
+
+  - BUILD_TUPLE: convert to a constant
+  - BUILD_TUPLE + UNPACK_SEQUENCE
+  - BUILD_LIST + UNPACK_SEQUENCE
+  - BUILD_LIST + COMPARE_OP(in/not in): convert list to tuple
+  - BUILD_SET + COMPARE_OP(in/not in): convert set to frozenset
+  - COMPARE_OP:
+
+    * replace ``not(a is b)`` with ``a is not b``
+    * replace ``not(a is not b)`` with ``a is b``
+    * replace ``not(a in b)`` with ``a not in b``
+    * replace ``not(a not in b)`` with ``a in b``
+
+* Dead code elimination
+
+  - Remove code after final operations in the current block:
+    see :meth:`Instr.is_final`
+  - Remove unreachable blocks (:class:`Block`)
+
+* Replace UNARY_NOT+POP_JUMP_IF_FALSE with POP_JUMP_IF_TRUE
+
+* Optimize jumps
+
+  - Replace unconditional jumps to RETURN_VALUE with RETURN_VALUE
+  - Replace jumps to unconditional jumps with jumps to the final target
+
+For tuples, constant folding is only run if the result has 20 items or less.
+
+By design, only basic optimizations can be implemented. A peephole optimizer
+has a narrow view on the bytecode (a few instructions) and only a very limited
+knownledge of the code.
+
+.. note::
+   ``3 < 5`` or ``(1, 2, 3)[1]`` are not optimized.
+
+
+API
+===
+
+.. class:: PeepholeOptimizer
+
+   .. method:: optimize(code: types.CodeType) -> types.CodeType
+
+      Optimize a Python code object.
+
+      Return a new optimized Python code object.
+
+
+.. class:: CodeTransformer
+
+   Code transformer for the API of the `PEP 511
+   <https://www.python.org/dev/peps/pep-0511/>`_ (API for code transformers).
+
+   .. method:: code_transformer(code, context)
+
+      Run the :class:`PeepholeOptimizer` optimizer on the code.
+
+      Return a new optimized Python code object.