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.

__firstlineno__ = 272

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

__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

__static_attributes__ = ('mount_point', 'mount_points', 'name', 'nr_snapshots', 'origin', 'snapshot_name', 'snapshot_uuid', 'timestamp', 'uuid')

__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(source, mount, free_space, fs_used, dev_size, policy)

Bases: object

Class representing a configured instance of a size policy.

__firstlineno__ = 556

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

Initialise a new SizePolicy object using the supplied parameters.

Parameters:

• source – The source for this SizePolicy: a mount point or block device path.

• mount – The mount point path if mounted.

• 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.

• policy – A size policy string.

Returns:

A SizePolicy object configured for the specified size.

__static_attributes__ = ('_dev_size', '_free_space', '_fs_used', '_mount', '_percent', '_size', '_source', 'type')

property size

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

class snapm.SizePolicyType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class representing the possible snapshot size policies.

FIXED = 'FIXED'

PERCENT_FREE = 'FREE'

PERCENT_SIZE = 'SIZE'

PERCENT_USED = 'USED'

class snapm.SnapStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

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

ACTIVE = 1

INACTIVE = 2

INVALID = 3

REVERTING = 4

__str__()

Return a string representation of this SnapStatus object.

Returns:

“Active”, “Inactive”, “Invalid”, or “Reverting”.

exception snapm.SnapmArgumentError

Bases: SnapmError

An invalid argument was passed to a snapshot manager API call.

__firstlineno__ = 260

__static_attributes__ = ()

exception snapm.SnapmBusyError

Bases: 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.

__annotations__ = {}

__firstlineno__ = 209

__static_attributes__ = ()

exception snapm.SnapmCalloutError

Bases: SnapmError

An error calling out to an external program.

__annotations__ = {}

__firstlineno__ = 179

__static_attributes__ = ()

exception snapm.SnapmError

Bases: Exception

Base class for snapshot manager errors.

__annotations__ = {}

__firstlineno__ = 173

__static_attributes__ = ()

exception snapm.SnapmExistsError

Bases: SnapmError

The named snapshot set already exists.

__annotations__ = {}

__firstlineno__ = 203

__static_attributes__ = ()

exception snapm.SnapmInvalidIdentifierError

Bases: SnapmError

An invalid identifier was given.

__annotations__ = {}

__firstlineno__ = 229

__static_attributes__ = ()

class snapm.SnapmLogger(name, level=0)

Bases: Logger

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

__firstlineno__ = 100

__static_attributes__ = ('mask_bits',)

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: SnapmError

No snapshot provider plugin was found.

__annotations__ = {}

__firstlineno__ = 191

__static_attributes__ = ()

exception snapm.SnapmNoSpaceError

Bases: SnapmError

Insufficient space is available for the requested operation.

__annotations__ = {}

__firstlineno__ = 185

__static_attributes__ = ()

exception snapm.SnapmNotFoundError

Bases: SnapmError

The requested object does not exist.

__annotations__ = {}

__firstlineno__ = 223

__static_attributes__ = ()

exception snapm.SnapmParseError

Bases: SnapmError

An error parsing user input.

__annotations__ = {}

__firstlineno__ = 235

__static_attributes__ = ()

exception snapm.SnapmPathError

Bases: SnapmError

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

__annotations__ = {}

__firstlineno__ = 216

__static_attributes__ = ()

exception snapm.SnapmPluginError

Bases: SnapmError

An error performing an action via a plugin.

__annotations__ = {}

__firstlineno__ = 241

__static_attributes__ = ()

exception snapm.SnapmRecursionError

Bases: SnapmError

A snapshot set source corresponds to a snapshot of another snapshot set.

__annotations__ = {}

__firstlineno__ = 253

__static_attributes__ = ()

exception snapm.SnapmSizePolicyError

Bases: SnapmError

An invalid size policy was specified.

__annotations__ = {}

__firstlineno__ = 197

__static_attributes__ = ()

exception snapm.SnapmStateError

Bases: SnapmError

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

__annotations__ = {}

__firstlineno__ = 247

__static_attributes__ = ()

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.

__firstlineno__ = 1154

__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.

__static_attributes__ = ('_mount_point', '_name', '_origin', '_snapset_name', '_snapshot_set', '_timestamp', '_uuid', 'provider')

__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.

check_resize(size_policy)

Check whether this snapshot can be resized or not by calling the provider plugin with the updated size_policy.

check_revert()

Check whether this snapshot can be reverted or not by calling the provider plugin to verify the state of the snapshot.

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.

rename(new_name)

Rename a snapshot within a snapshot set.

Parameters:

new_name – The new name for the snapshot.

resize(size_policy)

Attempt to resize this snapshot according to the updated size_policy.

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.

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 source

The block device or mount point from which this Snapshot was created.

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.

__firstlineno__ = 663

__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.

__static_attributes__ = ('_by_mount_point', '_by_origin', '_name', '_snapshots', '_timestamp', '_uuid', 'boot_entry', 'revert_entry')

__str__()

Return a string representation of this SnapshotSet.

Returns:

A multi-line string describing this snapshot set.

activate()

Attempt to activate all members of this SnapshotSet.

Raises:

SnapmPluginError if a plugin fails to perform the requested operation.

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.

deactivate()

Attempt to deactivate all members of this SnapshotSet.

Raises:

SnapmPluginError if a plugin fails to perform the requested operation.

delete()

Delete the on-disk representation of this SnapshotSet.

Raises:

SnapmBusyError if the snapshot set is in use. SnapmPluginError if an error occurs deleting snapshot set members.

property devices

The list of block devices in this snapshot set.

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.

rename(new_name)

Rename this SnapshotSet to new_name.

Raises:

SnapmError if a call to rename any member of the snapshot set fails.

resize(sources, size_policies)

Attempt to resize the SnapshotSet according to the list of sources and corresponding size_policy strings.

Raises:

SnapmNoSpaceError if there is insufficient space available for the requested operation.

revert()

Initiate a revert operation on this SnapshotSet.

Raises:

SnapmPluginError if a plugin fails to perform the requested operation.

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.

snapshot_by_source(source)

Return the snapshot corresponding to source.

Parameters:

source – The block device or mount point path to search for.

Returns:

A Snapshot object for the given source path.

Raises:

SnapmNotFoundError if the specified source path 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 sources

The list of souce mount points and block devices 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.bool_to_yes_no(value)

Convert boolean-like to yes/no string.

Return the string “yes” if value evaluates to True, or “no” otherwise.

Parameters:

value – A boolean value to interpet.

Returns:

A string value that is “yes” if value is True, or “no” otherwise.

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

Top level interface to the snapshot manager.

class snapm.manager.Manager

Bases: object

Snapshot Manager high level interface.

__firstlineno__ = 245

__init__()

__static_attributes__ = ('_boot_cache', 'by_name', 'by_uuid', 'plugins', 'snapshot_sets')

_check_recursion(origins)

Verify that each entry in origins corresponds to a device that is not a snapshot belonging to another snapshot set.

Parameters:

origins – A list of origin devices to check.

Raises:

SnapmRecursionError if an origin device is a snapshot.

_find_and_verify_plugins(sources, size_policies, _requested_provider=None)

Find snapshot provider plugins for each source in sources and verify that a provider exists for each source present.

Parameters:

• sources – A list of source mount point or block device paths.

• size_policies – A dictionary mapping sources to size policies.

Returns:

A dictionary mapping sources to plugins.

_set_autoactivate(snapset, auto=False)

Set autoactivation for snapset.

Parameters:

• snapset – The SnapshotSet object to operate on.

• auto – True to enable autoactivation or False otherwise.

_snapset_from_name_or_uuid(name=None, uuid=None)

Look a snapshot set up by name or uuid. Returns a SnapshotSet correponding to either name or uuid`, or raises ``SnapmError on error.

Parameters:

• name – The name of the snapshot set to look up.

• uuid – The UUID of the snapshot set to look up.

Returns:

A SnapshotSet corresponding to the given name or UUID.

Raises:

SnapmNotFoundError is the name or UUID cannot be found. SnapmInvalidIdentifierError if the name and UUID do not match.

_validate_snapset_name(name)

Validate a snapshot set name.

Returns if name is a valid snapshot set name or raises an appropriate exception otherwise.

Parameters:

name – The snapshot set name to validate.

Raises:

SnapmExistsError if the name is already in use, or SnapmInvalidIdentifierError if the name fails validation.

activate_snapshot_sets(selection)

Activate snapshot sets matching selection criteria selection.

Parameters:

selection – Selection criteria for snapshot sets to activate.

by_name = {}

by_uuid = {}

create_snapshot_set(name, source_specs, default_size_policy=None, boot=False, revert=False)

Create a snapshot set of the supplied mount points with the name name.

Parameters:

• name – The name of the snapshot set.

• source_specs – A list of mount point and block device paths to include in the set.

• default_size_policy – A default size policy to use for the set.

Raises:

SnapmExistsError if the name is already in use, or SnapmInvalidIdentifierError if the name fails validation.

create_snapshot_set_boot_entry(name=None, uuid=None)

Create a snapshot boot entry for the specified snapshot set.

Parameters:

• name – The name of the snapshot set.

• uuid – The UUID of the snapshot set.

create_snapshot_set_revert_entry(name=None, uuid=None)

Create a revert boot entry for the specified snapshot set.

Parameters:

• name – The name of the snapshot set.

• uuid – The UUID of the snapshot set.

deactivate_snapshot_sets(selection)

Deactivate snapshot sets matching selection criteria selection.

Parameters:

selection – Selection criteria for snapshot sets to deactivate.

delete_snapshot_sets(selection)

Remove snapshot sets matching selection criteria selection.

Parameters:

selection – Selection criteria for snapshot sets to remove.

discover_snapshot_sets()

Discover snapshot sets by calling into each plugin to find individual snapshots and then aggregating them together into snapshot sets.

Initialises the snapshot_sets, by_name and by_uuid members with the discovered snapshot sets.

find_snapshot_sets(selection=None)

Find snapshot sets matching selection criteria.

Parameters:

selection – Selection criteria to apply.

Returns:

A list of matching SnapshotSet objects.

find_snapshots(selection=None)

Find snapshots matching selection criteria.

Parameters:

selection – Selection criteria to apply.

Returns:

A list of matching Snapshot objects.

plugins = []

rename_snapshot_set(old_name, new_name)

Rename snapshot set old_name as new_name.

Parameters:

• old_name – The name of the snapshot set to be renamed.

• new_name – The new name of the snapshot set.

Raises:

SnapmExistsError if the name is already in use, or SnapmInvalidIdentifierError if the name fails validation.

resize_snapshot_set(source_specs, name=None, uuid=None, default_size_policy=None)

Resize snapshot set named name or having UUID uuid.

Request to resize each snapshot included in source_specs according to the given size policy, or apply default_size_policy if set.

Parameters:

• name – The name of the snapshot set to resize.

• uuid – The UUID of the snapshot set to resize.

• source_specs – A list of mount points and optional size policies.

• default_size_policy – A default size policy to apply to the resize.

revert_snapshot_set(name=None, uuid=None)

Revert snapshot set named name or having UUID uuid.

Request to revert each snapshot origin within each snapshot set to the state at the time the snapshot was taken.

Parameters:

• name – The name of the snapshot set to revert.

• uuid – The UUID of the snapshot set to revert.

revert_snapshot_sets(selection)

Revert snapshot sets matching selection criteria selection.

Request to revert each snapshot origin within each snapshot set to the state at the time the snapshot was taken.

Parameters:

selection – Selection criteria for snapshot sets to revert.

set_autoactivate(selection, auto=False)

Set autoactivation state for snapshot sets matching selection criteria selection.

Parameters:

• selection – Selection criteria for snapshot sets to set autoactivation.

• auto – True to enable autoactivation or False otherwise.

snapshot_sets = []

split_snapshot_set(name, new_name, source_specs)

Split the snapshot set named name into two snapshot sets, with new_name containing the listed sources and name containing all remaining snapshots.

If new_name is None the listed snapshot are removed from name and permanently deleted. This operation cannot be undone.

Parameters:

• name – The name of the snapshot set to split

• new_name – The name of the newly split off snapshot set

• sources – The list of sources to include in the new snapshot set

snapm.command module

The snapm.command module provides both the snapm command line interface infrastructure, and a simple procedural interface to the snapm library modules.

The procedural interface is used by the snapm command line tool, and may be used by application programs, or interactively in the Python shell by users who do not require all the features present in the snapm object API.

snapm.command.PR_PLUGIN = 4

Plugin report object type

snapm.command.PR_SNAPSET = 1

Snapshot set report object type

snapm.command.PR_SNAPSHOT = 2

Snapshot report object type

class snapm.command.ReportObj(snapset=None, snapshot=None, plugin=None)

Bases: object

Common report object for snapm reports

__firstlineno__ = 92

__init__(snapset=None, snapshot=None, plugin=None)

__static_attributes__ = ('plugin', 'snapset', 'snapshot')

snapm.command._activate_cmd(cmd_args)

Activate snapshot set command handler.

Attempt to activate the snapshot sets that match the given selection criteria.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._add_autoactivate_args(parser)

snapm.command._add_identifier_args(parser, snapset=False, snapshot=False)

Add snapshot set or snapshot identifier command line arguments.

snapm.command._add_json_arg(parser)

snapm.command._add_plugin_subparser(type_subparser)

Add subparser for ‘plugin’ commands.

Parameters:

type_subparser – Command type subparser

snapm.command._add_report_args(parser)

Add common reporting command line arguments.

snapm.command._add_snapset_subparser(type_subparser)

Add subparser for ‘snapset’ commands.

Parameters:

type_subparser – Command type subparser

snapm.command._add_snapshot_subparser(type_subparser)

Add subparser for ‘snapshot’ commands.

Parameters:

type_subparser – Command type subparser

snapm.command._autoactivate_cmd(cmd_args)

Autoactivation status snapshot set command handler.

Attempt to set the autoactivation status for snapshot set that match the given selection criteria.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._create_cmd(cmd_args)

Create snapshot set command handler. Attempt to create the specified snapshot set.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._deactivate_cmd(cmd_args)

Deactivate snapshot set command handler.

Attempt to deactivate the snapshot sets that match the given selection criteria.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._delete_cmd(cmd_args)

Delete snapshot set command handler.

Attempt to delete the specified snapshot set.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._do_print_type(report_fields, selected, output_fields=None, opts=None, sort_keys=None, title=None)

Print an object type report (snapshot set, snapshot)

Helper for list function that generate reports.

Format a set of snapshot set or snapshot objects matching the given criteria and format them as a report, returning the output as a string.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

Return type:

str

snapm.command._expand_fields(default_fields, output_fields)

Expand output fields list from command line arguments.

snapm.command._generic_list_cmd(cmd_args, select, opts, manager, print_fn)

Generic list command implementation.

Implements a simple list command that applies selection criteria and calls a print_*() API function to display results.

Callers should initialise identifier and select appropriately for the specific command arguments.

Parameters:

• cmd_args – the command arguments

• select – selection criteria

• opts – reporting options object

• print_fn – the API call to display results. The function must accept the selection, output_fields, opts, and sort_keys keyword arguments

Returns:

None

snapm.command._list_cmd(cmd_args)

List snapshot sets command handler.

List the snapshot sets that match the given selection criteria as a tabular report, with one snapshot set per row.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._plugin_list_cmd(cmd_args)

List available plugins.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._prune_cmd(cmd_args)

Prune snapshot set command handler.

Attempt to prune the specified sources from the given snapshot set.

Parameters:

cmd_args – Command line arguments for the command.

Returns:

integer status code returned from main()

snapm.command._rename_cmd(cmd_args)

Rename snapshot set command handler.

Attempt to rename the specified snapshot set.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._report_obj_types = [<snapm.report.ReportObjType object>, <snapm.report.ReportObjType object>, <snapm.report.ReportObjType object>]

Report object types table for snapm.command reports

snapm.command._report_opts_from_args(cmd_args)

snapm.command._resize_cmd(cmd_args)

Resize snapshot set command handler.

Attempt to resize the snapshots contained in the given snapshot set according to the corresponding size policy.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._revert_cmd(cmd_args)

Delete snapshot set command handler.

Attempt to revert the specified snapshot set.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._show_cmd(cmd_args)

Show snapshot set command handler.

Show the snapshot sets that match the given selection criteria as a multi-line report.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._snapshot_activate_cmd(cmd_args)

Activate snapshot command handler.

Attempt to activate the snapshots that match the given selection criteria.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._snapshot_autoactivate_cmd(cmd_args)

Autoactivate snapshot command handler.

Attempt to set autoactivation status for the snapshots that match the given selection criteria.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._snapshot_deactivate_cmd(cmd_args)

Deactivate snapshot command handler.

Attempt to deactivate the snapshots that match the given selection criteria.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._snapshot_list_cmd(cmd_args)

List snapshots command handler.

List the snapshot that match the given selection criteria as a tabular report, with one snapshot per row.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._snapshot_show_cmd(cmd_args)

Show snapshots command handler.

Show the snapshots that match the given selection criteria as a multi-line report.

Parameters:

cmd_args – Command line arguments for the command

Returns:

integer status code returned from main()

snapm.command._split_cmd(cmd_args)

Split snapshot set command handler.

Attempt to split the specified sources from the first snapshot set argument into the second.

Parameters:

cmd_args – Command line arguments for the command.

Returns:

integer status code returned from main()

snapm.command._str_indent(string, indent)

Indent all lines of a multi-line string.

Indent each line of the multi line string string to the specified indentation level.

Parameters:

• string – The string to be indented

• indent – The number of characters to indent by

Returns:

str

snapm.command.create_snapset(manager, name, sources, size_policy=None, boot=False, revert=False)

Create a new snapshot set from a list of mount point and block device source paths.

Parameters:

• manager – The manager context to use

• name – The name of the new snapshot set

• sources – A list of mount point or block devices to snapshot

• size_policy – The default size policy for this snapshot set.

• boot – Create a boot entry for this snapshot set.

• revert – Create a revert boot entry for this snapshot set.

snapm.command.delete_snapset(manager, selection)

Delete snapshot set matching selection criteria.

Parameters:

• manager – The manager context to use

• selection – Selection criteria for the snapshot set to remove.

snapm.command.main(args)

Main entry point for snapm.

snapm.command.print_plugins(manager, selection=None, output_fields=None, opts=None, sort_keys=None)

Print plugins matching selection criteria.

Format a set of snapm.manager.Plugin objects matching the given criteria, and output them as a report to the file given in opts.report_file.

Selection criteria are currently ignored for plugin reports.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

snapm.command.print_snapsets(manager, selection=None, output_fields=None, opts=None, sort_keys=None)

Print snapshot sets matching selection criteria.

Format a set of snapm.manager.SnapshotSet objects matching the given criteria, and output them as a report to the file given in opts.report_file.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

snapm.command.print_snapshots(manager, selection=None, output_fields=None, opts=None, sort_keys=None)

Print snapshots matching selection criteria.

Format a set of snapm.manager.Snapshot objects matching the given criteria, and output them as a report to the file given in opts.report_file.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

snapm.command.prune_snapset(manager, name, sources)

Prune snapshots from an existing snapshot set.

Remove snapshots from an existing snapshot set named name. The snapshot sources listed in sources are pruned (deleted) from the named snapshot set.

Parameters:

• name – The name of the snapshot set to prune.

• sources – The sources to prune from name.

Returns:

A SnapshotSet object representing the pruned snapshot set

snapm.command.rename_snapset(manager, old_name, new_name)

Rename a snapshot set from old_name to new_name.

snapm.command.resize_snapset(manager, sources, name=None, uuid=None, default_size_policy=None)

Resize snapshot set by name or UUID.

Parameters:

• manager – The manager context to use

• sources – A list of mount point or block devices to snapshot

• name – The name of the snapshot set to resize.

• uuid – The uuid of the snapshot set to resize.

• default_size_policy – The default size policy for this snapshot set.

snapm.command.revert_snapset(manager, name=None, uuid=None)

Revert snapshot set matching selection criteria.

Parameters:

• manager – The manager context to use

• selection – Selection criteria for the snapshot set to revert.

snapm.command.set_debug(debug_arg)

Set debugging mask from command line argument.

snapm.command.setup_logging(cmd_args)

Set up snapm logging.

snapm.command.show_snapsets(manager, selection=None, members=False, json=False)

Show snapshot sets matching selection criteria.

snapm.command.show_snapshots(manager, selection=None, json=False)

Show snapshots matching selection criteria.

snapm.command.shutdown_logging()

Shut down snapm logging.

snapm.command.split_snapset(manager, name, new_name, sources)

Split an existing snapshot set.

Split the snapshot set named name into two snapshot sets, including all sources listed in sources in the newly created snapshot set with name new_name.

Parameters:

• name – The name of the snapshot set to split.

• new_name – The name for the newly created snapshot set.

• sources – The sources to split from name to new_name.

Returns:

A SnapshotSet object representing the snapshot set named new_name.

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.

__firstlineno__ = 312

__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

__static_attributes__ = ('props', 'report', 'report_string', 'sort_value')

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_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

class snapm.report.FieldProperties(field_num=None, initial_width=0, width=0, objtype=None, dtype=None, align=None, hidden=False, implicit=False, sort_key=False, sort_dir=None, compact_one=False, compacted=False, sort_posn=None)

Bases: object

Properties of a field instance.

__firstlineno__ = 273

__init__(field_num=None, initial_width=0, width=0, objtype=None, dtype=None, align=None, hidden=False, implicit=False, sort_key=False, sort_dir=None, compact_one=False, compacted=False, sort_posn=None)

__static_attributes__ = ('align', 'compact_one', 'compacted', 'dtype', 'field_num', 'hidden', 'implicit', 'initial_width', 'objtype', 'sort_dir', 'sort_key', 'sort_posn', 'width')

class snapm.report.FieldType

Bases: object

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

__firstlineno__ = 216

__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

__static_attributes__ = ('align', 'desc', 'dtype', 'head', 'name', 'objtype', 'report_fn', 'width')

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.

__firstlineno__ = 522

__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.

__static_attributes__ = ('_already_reported', '_data', '_field_calc_needed', '_field_properties', '_fields', '_header_written', '_rows', '_sort_required', '_title', '_types', 'keys_count', 'opts', 'report_types')

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

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.

__firstlineno__ = 178

__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.

__static_attributes__ = ('data_fn', 'desc', 'objtype', 'prefix')

class snapm.report.ReportOpts

Bases: object

Options controlling the formatting and output of a report.

__eq__(other)

Return self==value.

__firstlineno__ = 99

__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>

__static_attributes__ = ('aligned', 'buffered', 'columns', 'columns_as_rows', 'field_name_prefix', 'headings', 'json', 'report_file', 'separator', 'unquoted')

__str__()

Return str(self).

snapm.manager.plugins module

Snapshot manager plugin interface.

class snapm.manager.plugins.Plugin(logger)

Bases: object

Abstract base class for snapshot manager plugins.

__firstlineno__ = 39

__init__(logger)

__static_attributes__ = ('logger', 'size_map')

_log_debug(*args)

Log at debug level.

_log_error(*args)

Log at error level.

_log_info(*args)

Log at info level.

_log_warn(*args)

Log at warning level.

activate_snapshot(name)

Activate the snapshot named name

Parameters:

name – The name of the snapshot to be activated.

can_snapshot(source)

Test whether this plugin can snapshot the specified mount point or block device.

Parameters:

source – The block device or mount point path to test.

Returns:

True if this plugin can snapshot the file system mounted at mount_point, or False otherwise.

check_create_snapshot(origin, snapset_name, timestamp, mount_point, size_policy)

Perform pre-creation checks before creating a snapshot.

Parameters:

• origin – The origin volume for the snapshot.

• snapset_name – The name of the snapshot set to be created.

• timestamp – The snapshot set timestamp.

• mount_point – The mount point path for this snapshot.

Raises:

SnapmNoSpaceError if there is insufficient free space to create the snapshot.

check_resize_snapshot(name, origin, mount_point, size_policy)

Chcek whether this snapshot can be resized to the requested size_policy. This method returns if the resize can be satisfied and raises an exception if not.

Returns:

None

Raises:

SnapmNoSpaceError if insufficient space is available to

satisfy the requested size policy or SnapmPluginError if another reason prevents the snapshot from being resized.

check_revert_snapshot(name, origin)

Check whether this snapshot can be reverted or not. This method returns if the current snapshot can be reverted and raises an exception if not.

Returns:

None

Raises:

NotImplementedError if this plugin does not support the

revert operation, SnapmBusyError if the snapshot is already in the process of being reverted to another snapshot state or SnapmPluginError if another reason prevents the snapshot from being merged.

create_snapshot(origin, snapset_name, timestamp, mount_point, size_policy)

Create a snapshot of origin in the snapset named snapset_name.

Parameters:

• origin – The origin volume for the snapshot.

• snapset_name – The name of the snapshot set to be created.

• timestamp – The snapshot set timestamp.

• mount_point – The mount point path for this snapshot.

Raises:

SnapmNoSpaceError if there is insufficient free space to create the snapshot.

deactivate_snapshot(name)

Deactivate the snapshot named name

Parameters:

name – The name of the snapshot to be deactivated.

delete_snapshot(name)

Delete the snapshot named name

Parameters:

name – The name of the snapshot to be removed.

discover_snapshots()

Discover snapshots managed by this plugin class.

Returns a list of objects that are a subclass of Snapshot. :returns: A list of snapshots discovered by this plugin class.

end_transaction()

End a snapshot set creation transaction in this plugin.

info()

Return plugin name and version.

name = 'plugin'

origin_from_mount_point(mount_point)

Return a string representing the origin from a given mount point path.

Parameters:

mount_point – The mount point path.

rename_snapshot(old_name, origin, snapset_name, timestamp, mount_point)

Rename the snapshot named old_name according to the provided snapshot field values.

Parameters:

• old_name – The original name of the snapshot to be renamed.

• origin – The origin volume for the snapshot.

• snapset_name – The new name of the snapshot set.

• timestamp – The snapshot set timestamp.

• mount_point – The mount point of the snapshot.

resize_snapshot(name, origin, mount_point, size_policy)

Attempt to resize the snapshot name to the requested size_policy. This method returns if the resize can be satisfied and raises an exception if not.

Returns:

None

Raises:

SnapmNoSpaceError if insufficient space is available to

satisfy the requested size policy or SnapmPluginError if another reason prevents the snapshot from being resized.

revert_snapshot(name)

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.

Parameters:

name – The name of the snapshot to revert.

set_autoactivate(name, auto=False)

Set the autoactivation state of the snapshot named name.

Parameters:

• name – The name of the snapshot to be modified.

• auto – True to enable autoactivation or False otherwise.

snapshot_class

alias of Snapshot

start_transaction()

Begin a snapshot set creation transaction in this plugin.

version = '0.1.0'

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.