CedarBackup3.actions.store
==========================

.. py:module:: CedarBackup3.actions.store

.. autoapi-nested-parse::

   Implements the standard 'store' action.
   :author: Kenneth J. Pronovici <pronovic@ieee.org>
   :author: Dmitry Rutsky <rutsky@inbox.ru>







Module Contents
---------------

.. py:data:: logger

.. py:function:: executeStore(configPath, options, config)

   Executes the store backup action.

   *Note:* The rebuild action and the store action are very similar.  The
   main difference is that while store only stores a single day's staging
   directory, the rebuild action operates on multiple staging directories.

   *Note:* When the store action is complete, we will write a store indicator to
   the daily staging directory we used, so it's obvious that the store action
   has completed.

   :param configPath: Path to configuration file on disk
   :type configPath: String representing a path on disk
   :param options: Program command-line options
   :type options: Options object
   :param config: Program configuration
   :type config: Config object

   :raises ValueError: Under many generic error conditions
   :raises IOError: If there are problems reading or writing files


.. py:function:: writeImage(config, newDisc, stagingDirs)

   Builds and writes an ISO image containing the indicated stage directories.

   The generated image will contain each of the staging directories listed in
   ``stagingDirs``.  The directories will be placed into the image at the root by
   date, so staging directory ``/opt/stage/2005/02/10`` will be placed into the
   disc at ``/2005/02/10``.

   *Note:* This function is implemented in terms of :any:`writeImageBlankSafe`.  The
   ``newDisc`` flag is passed in for both ``rebuildMedia`` and ``todayIsStart``.

   :param config: Config object
   :param newDisc: Indicates whether the disc should be re-initialized
   :param stagingDirs: Dictionary mapping directory path to date suffix

   :raises ValueError: Under many generic error conditions
   :raises IOError: If there is a problem writing the image to disc


.. py:function:: writeImageBlankSafe(config, rebuildMedia, todayIsStart, blankBehavior, stagingDirs)

   Builds and writes an ISO image containing the indicated stage directories.

   The generated image will contain each of the staging directories listed in
   ``stagingDirs``.  The directories will be placed into the image at the root by
   date, so staging directory ``/opt/stage/2005/02/10`` will be placed into the
   disc at ``/2005/02/10``.  The media will always be written with a media
   label specific to Cedar Backup.

   This function is similar to :any:`writeImage`, but tries to implement a smarter
   blanking strategy.

   First, the media is always blanked if the ``rebuildMedia`` flag is true.
   Then, if ``rebuildMedia`` is false, blanking behavior and ``todayIsStart``
   come into effect::

      If no blanking behavior is specified, and it is the start of the week,
      the disc will be blanked

      If blanking behavior is specified, and either the blank mode is "daily"
      or the blank mode is "weekly" and it is the start of the week, then
      the disc will be blanked if it looks like the weekly backup will not
      fit onto the media.

      Otherwise, the disc will not be blanked

   How do we decide whether the weekly backup will fit onto the media?  That is
   what the blanking factor is used for.  The following formula is used::

      will backup fit? = (bytes available / (1 + bytes required) <= blankFactor

   The blanking factor will vary from setup to setup, and will probably
   require some experimentation to get it right.

   :param config: Config object
   :param rebuildMedia: Indicates whether media should be rebuilt
   :param todayIsStart: Indicates whether today is the starting day of the week
   :param blankBehavior: Blank behavior from configuration, or ``None`` to use default behavior
   :param stagingDirs: Dictionary mapping directory path to date suffix

   :raises ValueError: Under many generic error conditions
   :raises IOError: If there is a problem writing the image to disc


.. py:function:: writeStoreIndicator(config, stagingDirs)

   Writes a store indicator file into staging directories.

   The store indicator is written into each of the staging directories when
   either a store or rebuild action has written the staging directory to disc.

   :param config: Config object
   :param stagingDirs: Dictionary mapping directory path to date suffix


.. py:function:: consistencyCheck(config, stagingDirs)

   Runs a consistency check against media in the backup device.

   It seems that sometimes, it's possible to create a corrupted multisession
   disc (i.e. one that cannot be read) although no errors were encountered
   while writing the disc.  This consistency check makes sure that the data
   read from disc matches the data that was used to create the disc.

   The function mounts the device at a temporary mount point in the working
   directory, and then compares the indicated staging directories in the
   staging directory and on the media.  The comparison is done via
   functionality in ``filesystem.py``.

   If no exceptions are thrown, there were no problems with the consistency
   check.  A positive confirmation of "no problems" is also written to the log
   with ``info`` priority.

   @warning: The implementation of this function is very UNIX-specific.

   :param config: Config object
   :param stagingDirs: Dictionary mapping directory path to date suffix

   :raises ValueError: If the two directories are not equivalent
   :raises IOError: If there is a problem working with the media


