discuss exact interfaces

pep-0552.txt

@@ -84,9 +84,27 @@ correctly, so out-of-band consistency checkers can verify the up-to-dateness of
 the pyc. Note also that the :pep:`3147` edict that pycs without corresponding
 source files not be loaded will still be enforced for hash-based pycs.
 
-The ``py_compile`` and ``compileall`` tools will be extended with new options to
-generate hash-based pycs with and without the ``check_source`` bit set. Their
-programmatic APIs will also gain similar functionality.
+The programmatic APIs of ``py_compile`` and ``compileall`` will support
+generation of hash-based pycs. Principally, ``py_compile`` will define a new
+enumeration corresponding to all the available pyc invalidation modules::
+
+  class PycInvalidationMode(Enum):
+      TIMESTAMP
+      CHECKED_HASH
+      UNCHECKED_HASH
+
+``py_compile.compile``, ``compileall.compile_dir``, and
+``compileall.compile_file`` will all gain an ``invalidation_mode`` parameter,
+which accepts a value of the ``PycInvalidationMode`` enumeration.
+
+The ``compileall`` tool will be extended with a command new option,
+``--invalidation-mode`` to generate hash-based pycs with and without the
+``check_source`` bit set. ``--invalidation-mode`` will be a tristate option
+taking values ``timestamp`` (the default), ``checked-hash``, and
+``unchecked-hash`` corresponding to the values of ``PycInvalidationMode``.
+
+``importlib`` will be extended with a ``source_hash(source)`` function that
+computes the hash used by the pyc writing code for a bytestring **source**.
 
 
 References