CedarBackup3.extend.capacity
============================

.. py:module:: CedarBackup3.extend.capacity

.. autoapi-nested-parse::

   Provides an extension to check remaining media capacity.

   Some users have asked for advance warning that their media is beginning to fill
   up.  This is an extension that checks the current capacity of the media in the
   writer, and prints a warning if the media is more than X% full, or has fewer
   than X bytes of capacity remaining.

   :author: Kenneth J. Pronovici <pronovic@ieee.org>









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

.. py:data:: logger

.. py:class:: PercentageQuantity(quantity=None)

   Class representing a percentage quantity.

   The percentage is maintained internally as a string so that issues of
   precision can be avoided.  It really isn't possible to store a floating
   point number here while being able to losslessly translate back and forth
   between XML and object representations.  (Perhaps the Python 2.4 Decimal
   class would have been an option, but I originally wanted to stay compatible
   with Python 2.3.)

   Even though the quantity is maintained as a string, the string must be in a
   valid floating point positive number.  Technically, any floating point
   string format supported by Python is allowble.  However, it does not make
   sense to have a negative percentage in this context.



   .. py:attribute:: quantity
      :value: None



   .. py:method:: __repr__()

      Official string representation for class instance.



   .. py:method:: __str__()

      Informal string representation for class instance.



   .. py:method:: __eq__(other)

      Equals operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __lt__(other)

      Less-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __gt__(other)

      Greater-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __cmp__(other)

      Original Python 2 comparison operator.
      Lists within this class are "unordered" for equality comparisons.
      :param other: Other object to compare to

      :returns: -1/0/1 depending on whether self is ``<``, ``=`` or ``>`` other



   .. py:attribute:: percentage


.. py:class:: CapacityConfig(maxPercentage=None, minBytes=None)

   Class representing capacity configuration.

   The following restrictions exist on data in this class:

      - The maximum percentage utilized must be a PercentageQuantity
      - The minimum bytes remaining must be a ByteQuantity



   .. py:attribute:: maxPercentage
      :value: None



   .. py:attribute:: minBytes
      :value: None



   .. py:method:: __repr__()

      Official string representation for class instance.



   .. py:method:: __str__()

      Informal string representation for class instance.



   .. py:method:: __eq__(other)

      Equals operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __lt__(other)

      Less-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __gt__(other)

      Greater-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __cmp__(other)

      Original Python 2 comparison operator.
      :param other: Other object to compare to

      :returns: -1/0/1 depending on whether self is ``<``, ``=`` or ``>`` other



.. py:class:: LocalConfig(xmlData=None, xmlPath=None, validate=True)

   Class representing this extension's configuration document.

   This is not a general-purpose configuration object like the main Cedar
   Backup configuration object.  Instead, it just knows how to parse and emit
   specific configuration values to this extension.  Third parties who need to
   read and write configuration related to this extension should access it
   through the constructor, ``validate`` and ``addConfig`` methods.

   *Note:* Lists within this class are "unordered" for equality comparisons.



   .. py:attribute:: capacity
      :value: None



   .. py:method:: __repr__()

      Official string representation for class instance.



   .. py:method:: __str__()

      Informal string representation for class instance.



   .. py:method:: __eq__(other)

      Equals operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __lt__(other)

      Less-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __gt__(other)

      Greater-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __cmp__(other)

      Original Python 2 comparison operator.
      Lists within this class are "unordered" for equality comparisons.
      :param other: Other object to compare to

      :returns: -1/0/1 depending on whether self is ``<``, ``=`` or ``>`` other



   .. py:method:: validate()

      Validates configuration represented by the object.
      THere must be either a percentage, or a byte capacity, but not both.
      :raises ValueError: If one of the validations fails



   .. py:method:: addConfig(xmlDom, parentNode)

      Adds a <capacity> configuration section as the next child of a parent.

      Third parties should use this function to write configuration related to
      this extension.

      We add the following fields to the document::

         maxPercentage  //cb_config/capacity/max_percentage
         minBytes       //cb_config/capacity/min_bytes

      :param xmlDom: DOM tree as from ``impl.createDocument()``
      :param parentNode: Parent that the section should be appended to



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

   Executes the capacity action.

   :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 I/O problems reading or writing files


