# Snapshot List

Snapshot filtering is performed using the `filter_` methods of `curator.SnapshotList`

class curator.SnapshotList(client, repository=None)

  Bases: `object`

  Snapshot list object

  client

    An `Elasticsearch` client object passed from param `client`

  empty_list_check()

    Raise exception if `snapshots` is empty

  filter_by_age(source='creation_date', direction=None, timestring=None, unit=None, unit_count=None, epoch=None, exclude=False)

    Remove snapshots from `snapshots` by relative age calculations.

    Parameters:

      - source – Source of snapshot age. Can be `name`, or `creation_date`.

      - direction – Time to filter, either `older` or `younger`

      - timestring – A `time.strftime()` string to match the datestamp in an snapshot name. Only used for snapshot filtering by `name`.

      - unit – One of `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, or `years`.

      - unit_count – The number of `unit` (s). `unit_count` * `unit` will be calculated out to the relative number of seconds.

      - epoch – An epoch timestamp used in conjunction with `unit` and `unit_count` to establish a point of reference for calculations. If not provided, the current time will be used.

      - exclude – If `exclude=True`, this filter will remove matching snapshots from `snapshots`. If `exclude=False`, then only matching snapshots will be kept in `snapshots`. Default is `False`

  filter_by_count(count=None, reverse=True, use_age=False, source='creation_date', timestring=None, exclude=True)

    Remove snapshots from the actionable list beyond the number `count`, sorted reverse-alphabetically by default. If you set `reverse=False`, it will be sorted alphabetically.

    The default is usually what you will want. If only one kind of snapshot is provided–for example, snapshots matching `curator-%Y%m%d%H%M%S`–then reverse alphabetical sorting will mean the oldest will remain in the list, because lower numbers in the dates mean older snapshots.

    By setting `reverse=False`, then `snapshot3` will be acted on before `snapshot2`, which will be acted on before `snapshot1`

    `use_age` allows ordering snapshots by age. Age is determined by the snapshot creation date (as identified by `start_time_in_millis`) by default, but you can also specify `source=name`. The `name` `source` requires the timestring argument.

    Parameters:

      - count – Filter snapshots beyond `count`.

      - reverse – The filtering direction. (default: `True`).

      - use_age – Sort snapshots by age. `source` is required in this case.

      - source – Source of snapshot age. Can be one of `name`, or `creation_date`. Default: `creation_date`

      - timestring – A `time.strftime()` string to match the datestamp in a snapshot name. Only used if `source=name`.

      - exclude – If `exclude=True`, this filter will remove matching snapshots from `snapshots`. If `exclude=False`, then only matching snapshots will be kept in `snapshots`. Default is `True`

  filter_by_regex(kind=None, value=None, exclude=False)

    Filter out snapshots not matching the pattern, or in the case of exclude, filter those matching the pattern.

    Parameters:

      - kind – Can be one of: `suffix`, `prefix`, `regex`, or `timestring`. This option defines what kind of filter you will be building.

      - value – Depends on `kind`. It is the `time.strftime()` string if `kind` is `timestring`. It’s used to build the regular expression for other kinds.

      - exclude – If `exclude=True`, this filter will remove matching snapshots from `snapshots`. If `exclude=False`, then only matching snapshots will be kept in `snapshots`. Default is `False`

  filter_by_state(state=None, exclude=False)

    Filter out snapshots not matching `state`, or in the case of exclude, filter those matching `state`.

    Parameters:

      - state – The snapshot state to filter for. Must be one of `SUCCESS`, `PARTIAL`, `FAILED`, or `IN_PROGRESS`.

      - exclude – If `exclude=True`, this filter will remove matching snapshots from `snapshots`. If `exclude=False`, then only matching snapshots will be kept in `snapshots`. Default is `False`

  filter_none()

    No filter at all

  filter_period(period_type='relative', source='name', range_from=None, range_to=None, date_from=None, date_to=None, date_from_format=None, date_to_format=None, timestring=None, unit=None, week_starts_on='sunday', epoch=None, exclude=False)

    Match `snapshots` with ages within a given period.

    Parameters:

      - period_type – Can be either `absolute` or `relative`. Default is `relative`. `date_from` and `date_to` are required when using `period_type='absolute'`. `range_from` and `range_to` are required with `period_type='relative'`.

      - source – Source of snapshot age. Can be `name`, or `creation_date`.

      - range_from – How many `unit` (s) in the past/future is the origin?

      - range_to – How many `unit` (s) in the past/future is the end point?

      - date_from – The simplified date for the start of the range

      - date_to – The simplified date for the end of the range. If this value is the same as `date_from`, the full value of `unit` will be extrapolated for the range. For example, if `unit=months`, and `date_from` and `date_to` are both `2017.01`, then the entire month of January 2017 will be the absolute date range.

      - date_from_format – The `time.strftime()` string used to parse `date_from`

      - date_to_format – The `time.strftime()` string used to parse `date_to`

      - timestring – An `time.strftime()` string to match the datestamp in an snapshot name. Only used for snapshot filtering by `name`.

      - unit – One of `hours`, `days`, `weeks`, `months`, or `years`.

      - week_starts_on – Either `sunday` or `monday`. Default is `sunday`

      - epoch – An epoch timestamp used to establish a point of reference for calculations. If not provided, the current time will be used.

      - exclude – If `exclude=True`, this filter will remove matching indices from `indices`. If `exclude=False`, then only matching indices will be kept in `indices`. Default is `False`

  iterate_filters(config)

    Iterate over the filters defined in `config` and execute them.

    Parameters:

      config – A dictionary of filters, as extracted from the YAML configuration file.

    Note

    `config` should be a dictionary with the following form:

        { 'filters' : [
                {
                    'filtertype': 'the_filter_type',
                    'key1' : 'value1',
                    ...
                    'keyN' : 'valueN'
                }
            ]
        }

  most_recent()

    Return the most recent snapshot based on `start_time_in_millis`.

  repository

    The value passed as `delete_aliases`

  snapshot_info

    Information extracted from snapshots, such as age, etc. Populated by internal method `__get_snapshots` at instance creation time. Type: `dict`

  snapshots

    The running list of snapshots which will be used by an Action class. Populated by internal methods `__get_snapshots` at instance creation time. Type: `list`

  working_list()

    Return the current value of `snapshots` as copy-by-value to prevent list stomping during iterations