snapm package¶
Module contents¶
Snapm top-level package.
- class snapm.Selection(name=None, uuid=None, basename=None, index=None, timestamp=None, nr_snapshots=None, mount_points=None, origin=None, mount_point=None, snapshot_name=None, snapshot_uuid=None)[source]¶
Bases:
object
Selection criteria for snapshot sets and snapshots.
- __firstlineno__ = 280¶
- __init__(name=None, uuid=None, basename=None, index=None, timestamp=None, nr_snapshots=None, mount_points=None, origin=None, mount_point=None, snapshot_name=None, snapshot_uuid=None)[source]¶
- __repr__()[source]¶
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__ = ('basename', 'index', 'mount_point', 'mount_points', 'name', 'nr_snapshots', 'origin', 'snapshot_name', 'snapshot_uuid', 'timestamp', 'uuid')¶
- __str__()[source]¶
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', 'basename', 'index', 'timestamp', 'nr_snapshots', 'mount_points', 'origin', 'mount_point', 'snapshot_name', 'snapshot_uuid']¶
- basename = None¶
- check_valid_selection(snapshot_set=False, snapshot=False)[source]¶
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 raiseValueError
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)[source]¶
Initialise Selection from command line arguments.
Construct a new
Selection
object from the command line arguments incmd_args
. Each set selection attribute fromcmd_args
is copied into the Selection. The resulting object may be passed to either theSnapshotSet
orSnapshot
search functions. (find_snapshot_sets
,find_snapshots
, as well as thesnapm.command
calls that accept a selection argument.- Parameters:
cmd_args – The command line selection arguments.
- Returns:
A new Selection instance
- Return type:
- index = None¶
- is_null()[source]¶
Test this Selection object for null selection criteria.
Return
True
if thisSelection
object matches all objects, orFalse
otherwise.- Returns:
True
if this Selection is null- Return type:
bool
- is_single()[source]¶
Test this Selection object for single item selction criteria.
Returns
True
if thisSelection
object matches a single object orFalse
otherwise.A
Selection
object matches a single object if either thename
oruuid
fields is specified.- Returns:
True
if this selection is single orFalse
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', 'basename', 'index', 'timestamp', 'nr_snapshots', 'mount_points']¶
- snapshot_uuid = None¶
- timestamp = None¶
- uuid = None¶
- class snapm.SizePolicy(source, mount, free_space, fs_used, dev_size, policy)[source]¶
Bases:
object
Class representing a configured instance of a size policy.
- __firstlineno__ = 572¶
- __init__(source, mount, free_space, fs_used, dev_size, policy)[source]¶
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(*values)[source]¶
Bases:
Enum
Enum class representing the possible snapshot size policies.
- FIXED = 'FIXED'¶
- PERCENT_FREE = 'FREE'¶
- PERCENT_SIZE = 'SIZE'¶
- PERCENT_USED = 'USED'¶
- class snapm.SnapStatus(*values)[source]¶
Bases:
Enum
Enum class representing snapshot status: Active, Inactive, Invalid or Reverting.
- ACTIVE = 1¶
- INACTIVE = 2¶
- INVALID = 3¶
- REVERTING = 4¶
- exception snapm.SnapmArgumentError[source]¶
Bases:
SnapmError
An invalid argument was passed to a snapshot manager API call.
- __firstlineno__ = 268¶
- __static_attributes__ = ()¶
- exception snapm.SnapmBusyError[source]¶
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__ = 217¶
- __static_attributes__ = ()¶
- exception snapm.SnapmCalloutError[source]¶
Bases:
SnapmError
An error calling out to an external program.
- __annotations__ = {}¶
- __firstlineno__ = 187¶
- __static_attributes__ = ()¶
- exception snapm.SnapmError[source]¶
Bases:
Exception
Base class for snapshot manager errors.
- __annotations__ = {}¶
- __firstlineno__ = 181¶
- __static_attributes__ = ()¶
- exception snapm.SnapmExistsError[source]¶
Bases:
SnapmError
The named snapshot set already exists.
- __annotations__ = {}¶
- __firstlineno__ = 211¶
- __static_attributes__ = ()¶
- exception snapm.SnapmInvalidIdentifierError[source]¶
Bases:
SnapmError
An invalid identifier was given.
- __annotations__ = {}¶
- __firstlineno__ = 237¶
- __static_attributes__ = ()¶
- class snapm.SnapmLogger(name, level=0)[source]¶
Bases:
Logger
Snapm logging wrapper class: wrap the Logger.debug() method to allow filtering of submodule debug messages by log mask.
- __firstlineno__ = 108¶
- __static_attributes__ = ('mask_bits',)¶
- debug_masked(msg, *args, **kwargs)[source]¶
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¶
- exception snapm.SnapmNoProviderError[source]¶
Bases:
SnapmError
No snapshot provider plugin was found.
- __annotations__ = {}¶
- __firstlineno__ = 199¶
- __static_attributes__ = ()¶
- exception snapm.SnapmNoSpaceError[source]¶
Bases:
SnapmError
Insufficient space is available for the requested operation.
- __annotations__ = {}¶
- __firstlineno__ = 193¶
- __static_attributes__ = ()¶
- exception snapm.SnapmNotFoundError[source]¶
Bases:
SnapmError
The requested object does not exist.
- __annotations__ = {}¶
- __firstlineno__ = 231¶
- __static_attributes__ = ()¶
- exception snapm.SnapmParseError[source]¶
Bases:
SnapmError
An error parsing user input.
- __annotations__ = {}¶
- __firstlineno__ = 243¶
- __static_attributes__ = ()¶
- exception snapm.SnapmPathError[source]¶
Bases:
SnapmError
An invalid path was supplied, for example attempting to snapshot something that is not a mount point or block device.
- __annotations__ = {}¶
- __firstlineno__ = 224¶
- __static_attributes__ = ()¶
- exception snapm.SnapmPluginError[source]¶
Bases:
SnapmError
An error performing an action via a plugin.
- __annotations__ = {}¶
- __firstlineno__ = 249¶
- __static_attributes__ = ()¶
- exception snapm.SnapmRecursionError[source]¶
Bases:
SnapmError
A snapshot set source corresponds to a snapshot of another snapshot set.
- __annotations__ = {}¶
- __firstlineno__ = 261¶
- __static_attributes__ = ()¶
- exception snapm.SnapmSizePolicyError[source]¶
Bases:
SnapmError
An invalid size policy was specified.
- __annotations__ = {}¶
- __firstlineno__ = 205¶
- __static_attributes__ = ()¶
- exception snapm.SnapmStateError[source]¶
Bases:
SnapmError
The status of an object does not allow an operation to proceed.
- __annotations__ = {}¶
- __firstlineno__ = 255¶
- __static_attributes__ = ()¶
- class snapm.Snapshot(name, snapset_name, origin, timestamp, mount_point, provider)[source]¶
Bases:
object
Base class for individual snapshots. Each snapshot plugin should subclass
Snapshot
to provide a specific implementation.- __firstlineno__ = 1217¶
- __init__(name, snapset_name, origin, timestamp, mount_point, provider)[source]¶
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__ = ('_basename', '_index', '_mount_point', '_name', '_origin', '_snapset_name', '_snapshot_set', '_timestamp', '_uuid', 'provider')¶
- __str__()[source]¶
Return a string representation of this
Snapshot
object.- Returns:
A multi-line string describing this snapshot.
- property autoactivate¶
The autoactivation status of this snapshot. Returns
True
if the snapshot is automatically activated orFalse
otherwise.
- check_resize(size_policy)[source]¶
Check whether this snapshot can be resized or not by calling the provider plugin with the updated
size_policy
.
- check_revert()[source]¶
Check whether this snapshot can be reverted or not by calling the provider plugin to verify the state of the 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.
- property index¶
The index of this snapshot, if set, or the special value
snapm.SNAPSHOT_INDEX_NONE
otherwise.
- 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 orFalse
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 orFalse
otherwise.
- property origin_options¶
File system options needed to specify the origin of this snapshot.
- rename(new_name)[source]¶
Rename a snapshot within a snapshot set.
- Parameters:
new_name – The new name for the snapshot.
- revert()[source]¶
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_basename¶
The basename of the snapshot set this snapshot belongs to, minus any index.
- 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 orFalse
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)[source]¶
Bases:
object
Representation of a set of snapshots taken at the same point in time and managed as a group.
- __firstlineno__ = 704¶
- __init__(name, timestamp, snapshots)[source]¶
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__ = ('_basename', '_by_mount_point', '_by_origin', '_index', '_name', '_snapshots', '_timestamp', '_uuid', 'boot_entry', 'revert_entry')¶
- __str__()[source]¶
Return a string representation of this
SnapshotSet
.- Returns:
A multi-line string describing this snapshot set.
- activate()[source]¶
Attempt to activate all members of this
SnapshotSet
.- Raises:
SnapmPluginError
if a plugin fails to perform the requested operation.
- property autoactivate¶
The overall autoactivation status of this snapshot set. Returns
True
if all snapshots within the set have autoactivate enabled orFalse
otherwise.
- property basename¶
The basename of this snapshot set, minus any index.
- deactivate()[source]¶
Attempt to deactivate all members of this
SnapshotSet
.- Raises:
SnapmPluginError
if a plugin fails to perform the requested operation.
- delete()[source]¶
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.
- property index¶
The index of this snapshot set, if set, or the special value
snapm.SNAPSET_INDEX_NONE
otherwise.
- json(members=False, pretty=False)[source]¶
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 thisSnapshotSet
are currently mounted, orFalse
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 thisSnapshotSet
are currently mounted, orFalse
otherwise.
- rename(new_name)[source]¶
Rename this
SnapshotSet
tonew_name
.- Raises:
SnapmError
if a call to rename any member of the snapshot set fails.
- resize(sources, size_policies)[source]¶
Attempt to resize the
SnapshotSet
according to the list ofsources
and correspondingsize_policy
strings.- Raises:
SnapmNoSpaceError
if there is insufficient space available for the requested operation.
- revert()[source]¶
Initiate a revert operation on this
SnapshotSet
.- Raises:
SnapmPluginError
if a plugin fails to perform the requested operation.
- snapshot_by_mount_point(mount_point)[source]¶
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 thisSnapshotSet
.
- snapshot_by_source(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 thisSnapshotSet
.
- 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 thisSnapshotSet
are currently mounted, orFalse
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, orSnapStatus.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)[source]¶
Convert boolean-like to yes/no string.
Return the string “yes” if
value
evaluates toTrue
, or “no” otherwise.- Parameters:
value – A boolean value to interpet.
- Returns:
A string value that is “yes” if
value
isTrue
, or “no” otherwise.
- snapm.get_debug_mask()[source]¶
Return the current debug mask for the
snapm
package.- Returns:
The current debug mask value
- Return type:
int
- snapm.is_size_policy(policy)[source]¶
Test whether a string is a valid size policy
- Parameters:
policy – A possible policy string to test.
- Returns:
True
ifpolicy
is a valid size policy string orFalse
otherwise.
- snapm.parse_size_with_units(value)[source]¶
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.
Submodules¶
snapm.manager module¶
Top level interface to the snapshot manager.
- class snapm.manager.Manager[source]¶
Bases:
object
Snapshot Manager high level interface.
- __firstlineno__ = 249¶
- __static_attributes__ = ('_boot_cache', 'by_name', 'by_uuid', 'plugins', 'snapshot_sets')¶
- _check_recursion(origins)[source]¶
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)[source]¶
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.
- _find_next_index(basename)[source]¶
Find the next index value for the recurring snapset with basename
basename
.- Parameters:
basename – The basename of the recurring snapset
- Returns:
An integer index value
- _set_autoactivate(snapset, auto=False)[source]¶
Set autoactivation for
snapset
.- Parameters:
snapset – The
SnapshotSet
object to operate on.auto –
True
to enable autoactivation orFalse
otherwise.
- _snapset_from_name_or_uuid(name=None, uuid=None)[source]¶
Look a snapshot set up by
name
oruuid
. Returns aSnapshotSet
correponding to eithername
oruuid`, 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)[source]¶
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, orSnapmInvalidIdentifierError
if the name fails validation.
- activate_snapshot_sets(selection)[source]¶
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, autoindex=False)[source]¶
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.
boot – Create a snapshot boot entry for this snapshot set.
revert – Create a revert boot entry for this snapshot set.
autoindex – Treat name as the basename of a recurring snapshot set and generate and append an appropriate index value.
- Raises:
SnapmExistsError
if the name is already in use, orSnapmInvalidIdentifierError
if the name fails validation.
- create_snapshot_set_boot_entry(name=None, uuid=None)[source]¶
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)[source]¶
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)[source]¶
Deactivate snapshot sets matching selection criteria
selection
.- Parameters:
selection – Selection criteria for snapshot sets to deactivate.
- delete_snapshot_sets(selection)[source]¶
Remove snapshot sets matching selection criteria
selection
.- Parameters:
selection – Selection criteria for snapshot sets to remove.
- discover_snapshot_sets()[source]¶
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
andby_uuid
members with the discovered snapshot sets.
- find_snapshot_sets(selection=None)[source]¶
Find snapshot sets matching selection criteria.
- Parameters:
selection – Selection criteria to apply.
- Returns:
A list of matching
SnapshotSet
objects.
- find_snapshots(selection=None)[source]¶
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)[source]¶
Rename snapshot set
old_name
asnew_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, orSnapmInvalidIdentifierError
if the name fails validation.
- resize_snapshot_set(source_specs, name=None, uuid=None, default_size_policy=None)[source]¶
Resize snapshot set named
name
or having UUIDuuid
.Request to resize each snapshot included in
source_specs
according to the given size policy, or applydefault_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)[source]¶
Revert snapshot set named
name
or having UUIDuuid
.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)[source]¶
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)[source]¶
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 orFalse
otherwise.
- snapshot_sets = []¶
- split_snapshot_set(name, new_name, source_specs)[source]¶
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)[source]¶
Bases:
object
Common report object for snapm reports
- __firstlineno__ = 95¶
- __static_attributes__ = ('plugin', 'snapset', 'snapshot')¶
- snapm.command._activate_cmd(cmd_args)[source]¶
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_identifier_args(parser, snapset=False, snapshot=False)[source]¶
Add snapshot set or snapshot identifier command line arguments.
- snapm.command._add_plugin_subparser(type_subparser)[source]¶
Add subparser for ‘plugin’ commands.
- Parameters:
type_subparser – Command type subparser
- snapm.command._add_snapset_subparser(type_subparser)[source]¶
Add subparser for ‘snapset’ commands.
- Parameters:
type_subparser – Command type subparser
- snapm.command._add_snapshot_subparser(type_subparser)[source]¶
Add subparser for ‘snapshot’ commands.
- Parameters:
type_subparser – Command type subparser
- snapm.command._autoactivate_cmd(cmd_args)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Expand output fields list from command line arguments.
- snapm.command._generic_list_cmd(cmd_args, select, opts, manager, print_fn)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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._resize_cmd(cmd_args)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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, autoindex=False)[source]¶
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.
autoindex – Treat name as the basename of a recurring snapshot set and generate and append an appropriate index value.
- snapm.command.delete_snapset(manager, selection)[source]¶
Delete snapshot set matching selection criteria.
- Parameters:
manager – The manager context to use
selection – Selection criteria for the snapshot set to remove.
- snapm.command.print_plugins(manager, selection=None, output_fields=None, opts=None, sort_keys=None)[source]¶
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 inopts.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)[source]¶
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 inopts.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)[source]¶
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 inopts.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)[source]¶
Prune snapshots from an existing snapshot set.
Remove snapshots from an existing snapshot set named
name
. The snapshot sources listed insources
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)[source]¶
Rename a snapshot set from
old_name
tonew_name
.
- snapm.command.resize_snapset(manager, sources, name=None, uuid=None, default_size_policy=None)[source]¶
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)[source]¶
Revert snapshot set matching selection criteria.
- Parameters:
manager – The manager context to use
selection – Selection criteria for the snapshot set to revert.
- snapm.command.show_snapsets(manager, selection=None, members=False, json=False)[source]¶
Show snapshot sets matching selection criteria.
- snapm.command.show_snapshots(manager, selection=None, json=False)[source]¶
Show snapshots matching selection criteria.
- snapm.command.split_snapset(manager, name, new_name, sources)[source]¶
Split an existing snapshot set.
Split the snapshot set named
name
into two snapshot sets, including all sources listed insources
in the newly created snapshot set with namenew_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
tonew_name
.
- Returns:
A
SnapshotSet
object representing the snapshot set namednew_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[source]¶
Bases:
object
A
Field
represents an instance of aFieldType
including its associated data values.- __firstlineno__ = 322¶
- __init__(report, props)[source]¶
Initialise a new Field object.
Initialise a Field object and configure the supplied
report
andprops
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_idx(value)[source]¶
Report an index value for this Field object.
Set the value for this field to the supplied
value
.- Parameters:
value – The index value to set
- Return type:
None
- report_num(value)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Report an arbitrary value for this Field object.
Set the value for this field to the supplied
value
, and set the field’ssort_value
to the suppliedsort_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)[source]¶
Bases:
object
Properties of a field instance.
- __firstlineno__ = 283¶
- __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)[source]¶
- __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[source]¶
Bases:
object
The
FieldType
class describes the properties of a field available in aReport
instance.- __firstlineno__ = 226¶
- __init__(objtype, name, head, desc, width, dtype, report_fn, align=None)[source]¶
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[source]¶
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 ofField
objects describing the required report.- __firstlineno__ = 551¶
- __init__(types, fields, output_fields, opts, sort_keys, title)[source]¶
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)[source]¶
Report data for object.
Add a row of data to this
Report
. Thedata
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.
- class snapm.report.ReportObjType[source]¶
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 thedata_fn
member may be simplylambda x: x
.- __firstlineno__ = 188¶
- __init__(objtype, desc, prefix, data_fn)[source]¶
Initialise ReportObjType.
Initialise a new
ReportObjType
object with the specifiedobjtype
,desc
, optionalprefix
anddata_fn
. Theobjtype
must be an integer power of two that is unique within a given report. Thedata_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[source]¶
Bases:
object
Options controlling the formatting and output of a report.
- __firstlineno__ = 109¶
- __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'>)[source]¶
Initialise ReportOpts object.
Initialise a
ReportOpts
object to control output of aReport
.- 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')¶
snapm.manager.plugins module¶
Snapshot manager plugin interface.
- class snapm.manager.plugins.Plugin(logger)[source]¶
Bases:
object
Abstract base class for snapshot manager plugins.
- __firstlineno__ = 39¶
- __static_attributes__ = ('logger', 'size_map')¶
- activate_snapshot(name)[source]¶
Activate the snapshot named
name
- Parameters:
name – The name of the snapshot to be activated.
- can_snapshot(source)[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 atmount_point
, orFalse
otherwise.
- check_create_snapshot(origin, snapset_name, timestamp, mount_point, size_policy)[source]¶
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)[source]¶
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)[source]¶
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 orSnapmPluginError
if another reason prevents the snapshot from being merged.
- create_snapshot(origin, snapset_name, timestamp, mount_point, size_policy)[source]¶
Create a snapshot of
origin
in the snapset namedsnapset_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)[source]¶
Deactivate the snapshot named
name
- Parameters:
name – The name of the snapshot to be deactivated.
- delete_snapshot(name)[source]¶
Delete the snapshot named
name
- Parameters:
name – The name of the snapshot to be removed.
- discover_snapshots()[source]¶
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.
- name = 'plugin'¶
- origin_from_mount_point(mount_point)[source]¶
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)[source]¶
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)[source]¶
Attempt to resize the snapshot
name
to the requestedsize_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)[source]¶
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)[source]¶
Set the autoactivation state of the snapshot named
name
.- Parameters:
name – The name of the snapshot to be modified.
auto –
True
to enable autoactivation orFalse
otherwise.
- version = '0.1.0'¶
- snapm.manager.plugins.decode_mount_point(mount_str)[source]¶
Parse the mount point component of a snapshot name.
- snapm.manager.plugins.device_from_mount_point(mount_point)[source]¶
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)[source]¶
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)[source]¶
Format structured snapshot name.
Format a snapshot name according to the snapshot manager naming format.