snapm package

Module contents

Snapm top-level package.

class snapm.Selection(name=None, uuid=None, timestamp=None, nr_snapshots=None, mount_points=None, origin=None, mount_point=None, snapshot_name=None, snapshot_uuid=None)

Bases: object

Selection criteria for snapshot sets and snapshots.

__init__(name=None, uuid=None, timestamp=None, nr_snapshots=None, mount_points=None, origin=None, mount_point=None, snapshot_name=None, snapshot_uuid=None)

Initialize self. See help(type(self)) for accurate signature.

__repr__()

Format this Selection object as a machine readable string.

The returned string may be passed to the Selection initialiser to duplicate the original Selection.

Returns

A machine readable string representation of this Selection object

Return type

string

__str__()

Format this Selection object as a human readable string.

Returns

A human readable string representation of this Selection object

Return type

string

all_attrs = ['name', 'uuid', 'timestamp', 'nr_snapshots', 'mount_points', 'origin', 'mount_point', 'snapshot_name', 'snapshot_uuid']

check_valid_selection(snapshot_set=False, snapshot=False)

Check a Selection for valid criteria.

Check this Selection object to ensure it contains only criteria that are valid for the specified object type(s).

Returns None if the object passes the check, or raise ValueError if invalid criteria exist.

:param snapshot_set Selection may include SnapshotSet data :param snapshot: Selection may include Snapshot data :returns: None on success :rtype: NoneType :raises: ValueError if excluded criteria are present

classmethod from_cmd_args(cmd_args)

Initialise Selection from command line arguments.

Construct a new Selection object from the command line arguments in cmd_args. Each set selection attribute from cmd_args is copied into the Selection. The resulting object may be passed to either the SnapshotSet or Snapshot search functions. (find_snapshot_sets, find_snapshots, as well as the snapm.command calls that accept a selection argument.

Parameters

cmd_args – The command line selection arguments.

Returns

A new Selection instance

Return type

Selection

is_null()

Test this Selection object for null selection criteria.

Return True if this Selection object matches all objects, or False otherwise.

Returns

True if this Selection is null

Return type

bool

is_single()

Test this Selection object for single item selction criteria.

Returns True if this Selection object matches a single object or False otherwise.

A Selection object matches a single object if either the name or uuid fields is specified.

Returns

True if this selection is single or False otherwise.

Return type

bool

mount_point = None

mount_points = None

name = None

nr_snapshots = None

origin = None

snapshot_attrs = ['origin', 'mount_point', 'snapshot_name', 'snapshot_uuid']

snapshot_name = None

snapshot_set_attrs = ['name', 'uuid', 'timestamp', 'nr_snapshots', 'mount_points']

snapshot_uuid = None

timestamp = None

uuid = None

class snapm.SizePolicy(mount, free_space, fs_used, dev_size, policy)

Bases: object

Class representing a configured instance of a size policy.

__init__(mount, free_space, fs_used, dev_size, policy)

Initialise a new SizePolicy object using the supplied parameters.

Parameters

• free_space – The free space available to provision the snapshot in bytes.

• fs_used – The current file system occupancy in bytes.

• dev_size – The origin device size in bytes.

Returns

A SizePolicy object configured for the specified size.

property size

Return the backing store size for a snapshot based on the policy configuration.

class snapm.SizePolicyType(value)

Bases: enum.Enum

Enum class representing the possible snapshot size policies.

FIXED = 'FIXED'

PERCENT_FREE = 'FREE'

PERCENT_SIZE = 'SIZE'

PERCENT_USED = 'USED'

class snapm.SnapStatus(value)

Bases: enum.Enum

Enum class representing snapshot status: Active, Inactive or Invalid.

ACTIVE = 1

INACTIVE = 2

INVALID = 3

exception snapm.SnapmBusyError

Bases: snapm._snapm.SnapmError

A resouce needed by the current command is already in use: for e.g. a snapshot merge is in progress for a previous snapshot set.

exception snapm.SnapmCalloutError

Bases: snapm._snapm.SnapmError

An error calling out to an external program.

exception snapm.SnapmError

Bases: Exception

Base class for snapshot manager errors.

exception snapm.SnapmExistsError

Bases: snapm._snapm.SnapmError

The named snapshot set already exists.

exception snapm.SnapmInvalidIdentifierError

Bases: snapm._snapm.SnapmError

An invalid identifier was given.

class snapm.SnapmLogger(name, level=0)

Bases: logging.Logger

Snapm logging wrapper class: wrap the Logger.debug() method to allow filtering of submodule debug messages by log mask.

debug_masked(msg, *args, **kwargs)

Log a debug message if it passes the current debug mask.

Log the specified message if it passes the current logger debug mask.

Parameters

msg – the message to be logged

Return type

None

mask_bits = 0

set_debug_mask(mask_bits)

Set the debug mask for this SnapmLogger.

This should normally be set to the SNAPM_DEBUG_* value corresponding to the snapm sub-module that this instance of SnapmLogger belongs to.

Parameters

mask_bits – The bits to set in this logger’s mask.

Return type

None

exception snapm.SnapmNoProviderError

Bases: snapm._snapm.SnapmError

No snapshot provider plugin was found.

exception snapm.SnapmNoSpaceError

Bases: snapm._snapm.SnapmError

Insufficient space is available for the requested operation.

exception snapm.SnapmNotFoundError

Bases: snapm._snapm.SnapmError

The requested object does not exist.

exception snapm.SnapmParseError

Bases: snapm._snapm.SnapmError

An error parsing user input.

exception snapm.SnapmPathError

Bases: snapm._snapm.SnapmError

An invalid path was supplied, for example attempting to snapshot something that is not a mount point.

exception snapm.SnapmPluginError

Bases: snapm._snapm.SnapmError

An error performing an action via a plugin.

exception snapm.SnapmStateError

Bases: snapm._snapm.SnapmError

The status of an object does not allow an operation to proceed.

class snapm.Snapshot(name, snapset_name, origin, timestamp, mount_point, provider)

Bases: object

Base class for individual snapshots. Each snapshot plugin should subclass Snapshot to provide a specific implementation.

__init__(name, snapset_name, origin, timestamp, mount_point, provider)

Initialise a new Snapshot object.

Parameters

• name – The name of the snapshot.

• snapset_name – The name of the SnapshotSet this snapshot is a part of.

• origin – The origin volume of the snapshot.

• timestamp – The creation timestamp of the snapshot set.

• mount_point – The mount point path this snapshot refers to.

• provider – The plugin providing this snapshot.

__str__()

Return a string representation of this Snapshot object.

Returns

A multi-line string describing this snapshot.

activate()

Activate this snapshot.

as_dict()

Return a representation of this snapshot as a dictionary.

property autoactivate

The autoactivation status of this snapshot. Returns True if the snapshot is automatically activated or False otherwise.

deactivate()

Deactivate this snapshot.

delete()

Delete this snapshot.

property devpath

The device path for this snapshot.

property free

The space available to this snapshot in bytes. For snapshots with fixed-size backstores this reflects the space remaining in the current backstore. For snapshots that dynamically allocate space to the snapshot it indicates the pooled space available.

invalidate_cache()

Invalidate any cached data describing this snapshot.

json(pretty=False)

Return a string representation of this Snapshot in JSON notation.

property mount_point

The mount point of this snapshot.

property mounted

Test whether either the snapshot or origin volume for this Snapshot is currently mounted and in use.

Returns

True if this snapshot or its origin is currently mounted or False otherwise.

property name

The name of this snapshot.

property origin

The origin of this snapshot.

property origin_mounted

Test whether the origin volume for this Snapshot is currently mounted and in use.

Returns

True if this snaphot’s prigin is currently mounted or False otherwise.

property origin_options

File system options needed to specify the origin of this snapshot.

property provider

The name of the plugin managing this snapshot.

rename(new_name)

Rename a snapshot within a snapshot set.

Parameters

new_name – The new name for the snapshot.

revert()

Request to revert a snapshot and revert the content of the origin volume to its state at the time of the snapshot.

This may be deferred until the next device activation or mount operation for the respective volume.

set_autoactivate(auto=False)

Set the autoactivation state of this snapshot.

Parameters

auto – True to enable autoactivation or False otherwise.

property size

The size of this snapshot in bytes. For snapshots with fixed-size backstores this reflects the size of the backstore. For snapshots that dynamically allocate space to the snapshot it reflects the device or volume size.

property snapset_name

The name of the snapshot set this snapshot belongs to.

property snapshot_mounted

Test whether the snapshot volume for this Snapshot is currently mounted and in use.

Returns

True if this snaphot is currently mounted or False otherwise.

property snapshot_set

The SnapshotSet this snapshot belongs to.

property status

The status of this snapshot. Returns a SnapStatus enum value representing the current state of the snapshot.

property time

The human readable timestamp of this snapshot.

property timestamp

The numerical timestamp of this snapshot.

property uuid

The UUID of this snapshot.

class snapm.SnapshotSet(name, timestamp, snapshots)

Bases: object

Representation of a set of snapshots taken at the same point in time and managed as a group.

__init__(name, timestamp, snapshots)

Initialise a new SnapshotSet object.

Parameters

• name – The name of this SnapshotSet.

• timestamp – The creation timestamp of this SnapshotSet.

• snapshots – A list of Snapshot objects to be included in this set.

__str__()

Return a string representation of this SnapshotSet.

Returns

A multi-line string describing this snapshot set.

as_dict(members=False)

Return a representation of this snapshot as a dictionary.

property autoactivate

The overall autoactivation status of this snapshot set. Returns True if all snapshots within the set have autoactivate enabled or False otherwise.

json(members=False, pretty=False)

Return a string representation of this SnapshotSet in JSON notation.

property mount_points

The list of mount points in this snapshot set.

property mounted

Test whether the either the origin or snapshot volumes for this SnapshotSet are currently mounted and in use.

Returns

True if any of the snaphots belonging to this SnapshotSet are currently mounted, or False otherwise.

property name

The name of this snapshot set.

property nr_snapshots

The number of snapshots in this snapshot set.

property origin_mounted

Test whether the origin volumes for this SnapshotSet are currently mounted and in use.

Returns

True if any of the snaphots belonging to this SnapshotSet are currently mounted, or False otherwise.

snapshot_by_mount_point(mount_point)

Return the snapshot corresponding to mount_point.

Parameters

mount_point – The mount point path to search for.

Returns

A Snapshot object for the given mount point.

Raises

SnapmNotFoundError if the specified mount point is not present in this SnapshotSet.

property snapshot_mounted

Test whether the snapshot volumes for this SnapshotSet are currently mounted and in use.

Returns

True if any of the snaphots belonging to this SnapshotSet are currently mounted, or False otherwise.

property snapshots

The list of snapshots in this snapshot set.

property status

The overall status of this snapshot set. Returns SnapStatus.ACTIVE if all members of the set are valid and active, SnapStatus.INACTIVE if any members are inactive, or SnapStatus.INVALID if any member of the set is invalid.

property time

The human readable timestamp of this snapshot set.

property timestamp

The numerical timestamp of this snapshot set.

property uuid

The UUID of this snapshot set.

snapm.get_debug_mask()

Return the current debug mask for the snapm package.

Returns

The current debug mask value

Return type

int

snapm.is_size_policy(policy)

Test whether a string is a valid size policy

Parameters

policy – A possible policy string to test.

Returns

True if policy is a valid size policy string or False otherwise.

snapm.parse_size_with_units(value)

Parse a size string with optional unit suffix and return a value in bytes,

Parameters

size – The size string to parse.

Returns

an integer size in bytes.

Raises

ValueError if the string could not be parsed as a valid size vale.

snapm.set_debug_mask(mask)

Set the debug mask for the snapm package.

Parameters

mask – the logical OR of the SNAPM_DEBUG_* values to log.

Return type

None

snapm.size_fmt(value)

Format a size in bytes as a human readable string.

Parameters

value – The integer value to format.

Returns

A human readable string reflecting value.

Submodules

snapm.manager module

snapm.command module

snapm.report module

The snapm reporting module contains a set of classes for creating simple text based tabular reports for a user-defined set of object types and fields. No restrictions are placed on the types of object that can be reported: users of the Report classes may define additional object types outside the snapm package and include these types in reports generated by the module.

The fields displayed in a specific report may be selected from the available set of fields by specifying a simple comma-separated string list of field names (in display order). In addition, custom multi-column sorting is possible using a similar string notation.

The Report module is closely based on the device-mapper reporting engine and shares many features and behaviours with device mapper reports.

class snapm.report.Field

Bases: object

A Field represents an instance of a FieldType including its associated data values.

__init__(report, props)

Initialise a new Field object.

Initialise a Field object and configure the supplied report and props attributes.

Parameters

• report – The Report that owns this field

• props – The FieldProperties object for this field

props = None

reference to the FieldProperties describing this field

report = None

reference to the containing Report

report_num(value)

Report a numeric value for this Field object.

Set the value for this field to the supplied value.

Parameters

value – The numeric value to set

Return type

None

report_sha(value)

Report a SHA value for this Field object.

Set the value for this field to the supplied value.

Parameters

value – The SHA value to set

Return type

None

report_size(value)

Report a size value for this Field object.

Set the value for this field to the supplied value, converted to a human readable string.

Parameters

value – The size value to set in bytes.

Return type

None

report_str(value)

Report a string value for this Field object.

Set the value for this field to the supplied value.

Parameters

value – The string value to set

Return type

None

report_str_list(value)

Report a string list value for this Field object.

Set the value for this field to the strings contained in value.

Parameters

value – A list of strings

Return type

None

report_string = None

The formatted string to be reported for this field.

report_time(value)

Report a time value for this Field object.

Set the value for this field to the supplied value.

Parameters

value – The time value to set

Return type

None

report_uuid(value)

Report a uuid value for this Field object.

Set the value for this field to the supplied value.

Parameters

value – The uuid value to set

Return type

None

set_value(report_string, sort_value=None)

Report an arbitrary value for this Field object.

Set the value for this field to the supplied value, and set the field’s sort_value to the supplied sort_value.

Parameters

• report_string – The string value to set

• sort_value – The sort value

Return type

None

sort_value = None

The raw value of this field. Used for sorting.

class snapm.report.FieldProperties

Bases: object

Properties of a field instance.

align = None

compact_one = False

compacted = False

dtype = None

field_num = None

hidden = False

implicit = False

initial_width = 0

objtype = None

sort_dir = None

sort_key = False

sort_posn = None

width = 0

class snapm.report.FieldType

Bases: object

The FieldType class describes the properties of a field available in a Report instance.

__init__(objtype, name, head, desc, width, dtype, report_fn, align=None)

Initialise new FieldType object.

Initialise a new FieldType object with the specified properties.

Parameters

• objtype – The numeric object type ID (power of two)

• name – The field name used to select display fields

• desc – A human-readable description of the field

• width – The default (initial) field width

• dtype – The Report data type of the field

• report_fn – The field reporting function

• align – The field alignment value

Returns

A new ReportFieldType object

Return type

ReportFieldType

align = None

desc = None

dtype = None

head = None

name = None

objtype = -1

report_fn = None

width = 8

class snapm.report.Report

Bases: object

A class representing a configurable text report with multiple caller-defined fields. An optional title may be provided and the fields argument must contain a list of Field objects describing the required report.

__init__(types, fields, output_fields, opts, sort_keys, title)

Initialise Report.

Initialise a new Report object with the specified fields and output control options.

Parameters

• types – List of ReportObjType used in this report.

• fields – A list of Field field descriptions.

• output_fields – An optional list of output fields to be rendered by this report.

• opts – An instance of ReportOpts or None.

Returns

A new report object.

Return type

Report.

keys_count = 0

opts = None

report_object(obj)

Report data for object.

Add a row of data to this Report. The data argument should be an object of the type understood by this report’s fields. It will be passed in turn to each field to obtain data for the current row.

Parameters

obj – the object to report on for this row.

report_output()

Output report data.

Output this report’s data to the configured report file, using the configured output controls and fields.

On success the number of rows output is returned. On error an exception is raised.

Returns

the number of rows of output written.

Return type

int

report_types = 0

class snapm.report.ReportObjType

Bases: object

Class representing a type of object to be reported on. Instances of ReportObjType must specify an identifier, a description, and a data function that will return the correct type of object from a compound object containing data objects of different types. For reports that use only a single object type the data_fn member may be simply lambda x: x.

__init__(objtype, desc, prefix, data_fn)

Initialise ReportObjType.

Initialise a new ReportObjType object with the specified objtype, desc, optional prefix and data_fn. The objtype must be an integer power of two that is unique within a given report. The data_fn should accept an object as its only argument and return an object of the requested type.

data_fn = None

desc = ''

objtype = -1

prefix = ''

class snapm.report.ReportOpts

Bases: object

Options controlling the formatting and output of a report.

__eq__(other)

Return self==value.

__hash__ = None

__init__(columns=80, headings=True, buffered=True, separator=' ', field_name_prefix='', unquoted=True, aligned=True, json=False, columns_as_rows=False, report_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Initialise ReportOpts object.

Initialise a ReportOpts object to control output of a Report.

Parameters

• columns – the number of columns to use for output.

• headings – a boolean indicating whether to output column headings for this report.

• buffered – a boolean indicating whether to buffer output from this report.

• report_file – a file to which output will be sent.

Returns

a new ReportOpts object.

Return type

<class ReportOpts>

__str__()

Return str(self).

aligned = True

buffered = True

columns = 0

columns_as_rows = False

field_name_prefix = None

headings = True

json = False

report_file = None

separator = None

unquoted = True

snapm.manager.plugins module

Snapshot manager plugin interface.

snapm.manager.plugins.decode_mount_point(mount_str)

Parse the mount point component of a snapshot name.

snapm.manager.plugins.device_from_mount_point(mount_point)

Convert a mount point path to a corresponding device path.

Return the device corresponding to the file system mount point mount_point according to /proc/self/mounts.

snapm.manager.plugins.encode_mount_point(mount_point)

Encode mount point paths.

Encode a mount point for use in a snapshot name by replacing the path separator with ‘-‘.

snapm.manager.plugins.format_snapshot_name(origin, snapset_name, timestamp, mount_point)

Format structured snapshot name.

Format a snapshot name according to the snapshot manager naming format.

snapm.manager.plugins.mount_point_space_used(mount_point)

Retrieve space usage for a mount point path.

Return the space used on the file system mounted at mount_point as a value in bytes.

snapm.manager.plugins.parse_snapshot_name(full_name, origin)

Attempt to parse a snapshot set snapshot name.

Returns a tuple of (snapset_name, timestamp, mount_point) if full_name is a valid snapset snapshot name, or None otherwise.