"certbot.reverter"
******************

Reverter class saves configuration checkpoints and allows for
recovery.

class certbot.reverter.Reverter(config)

   Bases: "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
   "add_to_temp_checkpoint()" and reverted when
   "revert_temporary_config()" or "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
   "add_to_checkpoint()" and reverted when "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 "finalize_checkpoint()". Changes in this
   state can be reverted through calls to "rollback_checkpoints()".

   As a final note, creating new files and registering undo commands
   are handled specially and use the methods
   "register_file_creation()" and "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.

   Parameters:
      **config** ("certbot.interfaces.IConfig") – Configuration.

   revert_temporary_config()

      Reload users original configuration files after a temporary
      save.

      This function should reinstall the users original configuration
      files for all saves with temporary=True

      Raises:
         **ReverterError** – when unable to revert config

   rollback_checkpoints(rollback=1)

      Revert ‘rollback’ number of configuration checkpoints.

      Parameters:
         **rollback** (*int*) – Number of checkpoints to reverse. A
         str num will be cast to an integer. So “2” is also
         acceptable.

      Raises:
         **ReverterError** – if there is a problem with the input or
         if the function is unable to correctly revert the
         configuration checkpoints

   view_config_changes(for_logging=False, num=None)

      Displays all saved checkpoints.

      All checkpoints are printed by
      "certbot.interfaces.IDisplay.notification()".

      Todo: Decide on a policy for error handling, OSError IOError…

      Raises:
         **errors.ReverterError** – If invalid directory structure.

   add_to_temp_checkpoint(save_files, save_notes)

      Add files to temporary checkpoint.

      Parameters:
         * **save_files** (*set*) – set of filepaths to save

         * **save_notes** (*str*) – notes about changes during the
           save

   add_to_checkpoint(save_files, save_notes)

      Add files to a permanent checkpoint.

      Parameters:
         * **save_files** (*set*) – set of filepaths to save

         * **save_notes** (*str*) – notes about changes during the
           save

   _add_to_checkpoint_dir(cp_dir, save_files, save_notes)

      Add save files to checkpoint directory.

      Parameters:
         * **cp_dir** (*str*) – Checkpoint directory filepath

         * **save_files** (*set*) – set of files to save

         * **save_notes** (*str*) – notes about changes made during
           the save

      Raises:
         * **IOError** – if unable to open cp_dir + FILEPATHS file

         * **ReverterError** – if unable to add checkpoint

   _read_and_append(filepath)

      Reads the file lines and returns a file obj.

      Read the file returning the lines, and a pointer to the end of
      the file.

   _recover_checkpoint(cp_dir)

      Recover a specific checkpoint.

      Recover a specific checkpoint provided by cp_dir Note: this
      function does not reload augeas.

      Parameters:
         **cp_dir** (*str*) – checkpoint directory file path

      Raises:
         **errors.ReverterError** – If unable to recover checkpoint

   _run_undo_commands(filepath)

      Run all commands in a file.

   _check_tempfile_saves(save_files)

      Verify save isn’t overwriting any temporary files.

      Parameters:
         **save_files** (*set*) – Set of files about to be saved.

      Raises:
         **certbot.errors.ReverterError** – when save is attempting to
         overwrite a temporary file.

   register_file_creation(temporary, *files)

      Register the creation of all files during certbot execution.

      Call this method before writing to the file to make sure that
      the file will be cleaned up if the program exits unexpectedly.
      (Before a save occurs)

      Parameters:
         * **temporary** (*bool*) – If the file creation registry is
           for a temp or permanent save.

         * ***files** – file paths (str) to be registered

      Raises:
         **certbot.errors.ReverterError** – If call does not contain
         necessary parameters or if the file creation is unable to be
         registered.

   register_undo_command(temporary, command)

      Register a command to be run to undo actions taken.

      Warning: This function does not enforce order of operations in
        terms of file modification vs. command registration.  All undo
        commands are run first before all normal files are reverted to
        their previous state.  If you need to maintain strict order,
        you may create checkpoints before and after the the command
        registration. This function may be improved in the future
        based on demand.

      Parameters:
         * **temporary** (*bool*) – Whether the command should be
           saved in the IN_PROGRESS or TEMPORARY checkpoints.

         * **command** (*list of str*) – Command to be run.

   _get_cp_dir(temporary)

      Return the proper reverter directory.

   recovery_routine()

      Revert configuration to most recent finalized checkpoint.

      Remove all changes (temporary and permanent) that have not been
      finalized. This is useful to protect against crashes and other
      execution interruptions.

      Raises:
         **errors.ReverterError** – If unable to recover the
         configuration

   _remove_contained_files(file_list)

      Erase all files contained within file_list.

      Parameters:
         **file_list** (*str*) – file containing list of file paths to
         be deleted

      Returns:
         Success

      Return type:
         bool

      Raises:
         **certbot.errors.ReverterError** – If all files within
         file_list cannot be removed

   finalize_checkpoint(title)

      Finalize the checkpoint.

      Timestamps and permanently saves all changes made through the
      use of "add_to_checkpoint()" and "register_file_creation()"

      Parameters:
         **title** (*str*) – Title describing checkpoint

      Raises:
         **certbot.errors.ReverterError** – when the checkpoint is not
         able to be finalized.

   _checkpoint_timestamp()

      Determine the timestamp of the checkpoint, enforcing
      monotonicity.

   _timestamp_progress_dir()

      Timestamp the checkpoint.
