AutoArchive._application.archiving.archive_spec — AutoArchive Developer Manual (ver. 2.1.0.dev20260309)

# AutoArchive._application.archiving.archive_spec

ArchiveSpec component.

Implements ability to read archive configuration from archive specification file.

## Modules

### archive_spec

class AutoArchive._application.archiving.archive_spec.archive_spec.ArchiveSpec(specFile, configuration, componentUi=None)

  Bases: `ConfigurationBase`

  The archive specification.

  Contains all information needed to create the backup such as the name, list of files which shall be included into the backup, list of files to exclude, etc. These values can be configured in the archive specification file (`specFile`) or in the general configuration such as command line or configuration files. Options that can be read from this class are defined as static attributes of `ArchiveSpecOptions` and `Options`. If an option is not defined in the archive specification file it is read from `configuration`.

  The instance is fully populated during construction.

  Parameters:

    - specFile (`str`) – Archive specification file name (the “.aa file”).

    - configuration (`ConfigurationBase`) – The application’s configuration.

    - componentUi (`CmdlineUi`) – The application’s UI interface. If `None` then messages about non-accessible files or other errors during processing of included and excluded file lists will not be shown.

  Raises:

    - OSError – If `specFile` can not be opened.

    - LookupError – If a section or an option is missing in `specFile`.

    - SyntaxError – If `specFile` can not be parsed.

    - KeyError – If an invalid (unsupported) section or option is found in the archive specification file.

    - ValueError – If option’s value is not correct.

  getRawValue(option: Option) → Any | None

    See: `ConfigurationBase.getRawValue()`.

  isOptionPresent(option: Option) → bool

    Determines whether `option` is specified (e. g. in command line or a configuration file).

    Parameters:

      option (`Option`) – The option which presence shall be determined.

    Returns:

      `True` if `option` is present, `False` otherwise.

    Return type:

      `bool`

    Raises:

      KeyError – If `option` does not exists.

### archive_spec_options

`ArchiveSpecOptions` class.

class AutoArchive._application.archiving.archive_spec.archive_spec_options.ArchiveSpecOptions

  Bases: `object`

  Constants for options used specifically in the archive specification file.

  These constants should be used to access options in `ArchiveSpec`.

  Note

  It is not allowed to change values of these constants.

  EXCLUDE_FILES = <Option exclude-files of type <class 'str'>>

    Files and directories that will be excluded from the backup (`frozenset<str>`). Note that frozenset<str> is not supported by `OptionsUtils.strToOptionType()`; it is not used while populating this option. Guaranteed to be defined.

  INCLUDE_FILES = <Option include-files of type <class 'str'>>

    Files and directories that will be included in the backup (`frozenset<str>`). Note that frozenset<str> is not supported by `OptionsUtils.strToOptionType()`; it is not used while populating this option. Guaranteed to be defined.

  NAME = <Option name of type <class 'str'>>

    Archive name (`str`). Guaranteed to be defined.

  PATH = <Option path of type path>

    Path to the base directory for `INCLUDE_FILES`, `EXCLUDE_FILES` (`SpecialOptionTypes.PATH`). Guaranteed to be defined.

### config_constants

`ArchiveSpecInfo` and `ConfigConstants`.

class AutoArchive._application.archiving.archive_spec.config_constants.ArchiveSpecInfo(name, path)

  Bases: `tuple`

  Holds information about an archive specification file; its name and full path.

  name

    Alias for field number 0

  path

    Alias for field number 1

class AutoArchive._application.archiving.archive_spec.config_constants.ConfigConstants

  Bases: `object`

  Configuration related constants.

  ARCHIVE_SPEC_EXT = '.aa'

    Extension of archive specification files.

### _archive_spec_config_parser

`_ArchiveSpecConfigParser` class.

class AutoArchive._application.archiving.archive_spec._archive_spec_config_parser._ArchiveSpecConfigParser(forbiddenOptions, archiveSpecsDir)

  Bases: `ConfigParser`

  `configparser.ConfigParser` with specifics regards to archive specification file reading.

  Supports external references, empty values and adapted exception handling.

  Parameters:

    - forbiddenOptions (collections.abc.Set[str]) – Options which are not allowed in `_Sections.ARCHIVE` and `_Sections.CONTENT`

    - archiveSpecsDir (str) – Directory where to look for external archive specification files without path

  get(section, *args, **kwargs)

    Gets value and resolve external references.

    Parameters:

      - section (str) – Section the value shall be read from.

      - args – See `configparser.ConfigParser.get()`.

      - kwargs – See `configparser.ConfigParser.get()`.

    Raises:

      - RuntimeError – If directory where the configuration file is located is not known. `read_file()` has to be called first.

      - ValueError – If an external reference can not be resolved.

  optionxform(optionStr)

    Override that does not modify option name.

    Parameters:

      optionStr (str) – The option name.

    Returns:

      Unmodified option name.

    Return type:

      str

  read_file(file, source=None)

    Read configuration file with sanity checking and error handling.

    Parameters:

      - file – The file handle that shall be read.

      - source (str) – Path to the file that passed handle represents.

    Raises:

      - ValueError – If name of the source file can not be determined. If an empty option is present.

      - KeyError – If an invalid (unsupported) section or option is found in the archive specification file.

      - SyntaxError – If the file can not be parsed.

### _sections

`_Sections`.

class AutoArchive._application.archiving.archive_spec._sections._Sections

  Bases: `object`

  archive specification file section names.

  ARCHIVE = 'Archive'

    Contains options that modifies aspects of the backup creation.

  CONTENT = 'Content'

    Parameters of the archive.

  EXTERNAL = 'External'

    Contains referenced archive specification files.