Merge pull request #3208 from certbot/how2plugin

Better document plugins and reversion

certbot/interfaces.py

@@ -180,6 +180,9 @@ class IAuthenticator(IPlugin):
     def cleanup(achalls):
         """Revert changes and shutdown after challenges complete.
 
+        This method should be able to revert all changes made by
+        perform, even if perform exited abnormally.
+
         :param list achalls: Non-empty (guaranteed) list of
             :class:`~certbot.achallenges.AnnotatedChallenge`
             instances, a subset of those previously passed to :func:`perform`.
@@ -238,6 +241,14 @@ class IInstaller(IPlugin):
 
     Represents any server that an X509 certificate can be placed.
 
+    It is assumed that :func:`save` is the only method that finalizes a
+    checkpoint. This is important to ensure that checkpoints are
+    restored in a consistent manner if requested by the user or in case
+    of an error.
+
+    Using :class:`certbot.reverter.Reverter` to implement checkpoints,
+    rollback, and recovery can dramatically simplify plugin development.
+
     """
 
     def get_all_names():
@@ -304,8 +315,11 @@ class IInstaller(IPlugin):
 
         Both title and temporary are needed because a save may be
         intended to be permanent, but the save is not ready to be a full
-        checkpoint. If an exception is raised, it is assumed a new
+        checkpoint.
-        checkpoint was not created.
+
+        It is assumed that at most one checkpoint is finalized by this
+        method. Additionally, if an exception is raised, it is assumed a
+        new checkpoint was not finalized.
 
         :param str title: The title of the save. If a title is given, the
             configuration will be saved as a new checkpoint and put in a

certbot/reverter.py

@@ -24,6 +24,39 @@ logger = logging.getLogger(__name__)
 class Reverter(object):
     """Reverter Class - save and revert configuration checkpoints.
 
+    This class can be used by the plugins, especially Installers, to
+    undo changes made to the user's system. Modifications to files and
+    commands to do undo actions taken by the plugin should be registered
+    with this class before the action is taken.
+
+    Once a change has been registered with this class, there are three
+    states the change can be in. First, the change can be a temporary
+    change. This should be used for changes that will soon be reverted,
+    such as config changes for the purpose of solving a challenge.
+    Changes are added to this state through calls to
+    :func:`~add_to_temp_checkpoint` and reverted when
+    :func:`~revert_temporary_config` or :func:`~recovery_routine` is
+    called.
+
+    The second state a change can be in is in progress. These changes
+    are not temporary, however, they also have not been finalized in a
+    checkpoint. A change must become in progress before it can be
+    finalized. Changes are added to this state through calls to
+    :func:`~add_to_checkpoint` and reverted when
+    :func:`~recovery_routine` is called.
+
+    The last state a change can be in is finalized in a checkpoint. A
+    change is put into this state by first becoming an in progress
+    change and then calling :func:`~finalize_checkpoint`. Changes
+    in this state can be reverted through calls to
+    :func:`~rollback_checkpoints`.
+
+    As a final note, creating new files and registering undo commands
+    are handled specially and use the methods
+    :func:`~register_file_creation` and :func:`~register_undo_command`
+    respectively. Both of these methods can be used to create either
+    temporary or in progress changes.
+
     .. note:: Consider moving everything over to CSV format.
 
     :param config: Configuration.