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)[source]¶ Bases:
object
Selection criteria for snapshot sets and snapshots.
-
__init__
(name=None, uuid=None, timestamp=None, nr_snapshots=None, mount_points=None, origin=None, mount_point=None, snapshot_name=None, snapshot_uuid=None)[source]¶ Initialize self. See help(type(self)) for accurate signature.
-
__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
-
__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', 'timestamp', 'nr_snapshots', 'mount_points', 'origin', 'mount_point', 'snapshot_name', 'snapshot_uuid']¶
-
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
-
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', 'timestamp', 'nr_snapshots', 'mount_points']¶
-
snapshot_uuid
= None¶
-
timestamp
= None¶
-
uuid
= None¶
-
-
class
snapm.
SizePolicy
(mount, free_space, fs_used, dev_size, policy)[source]¶ Bases:
object
Class representing a configured instance of a size policy.
-
__init__
(mount, free_space, fs_used, dev_size, policy)[source]¶ Initialise a new SizePolicy object using the supplied parameters.
- Parameters
free_space – The free space available to provision the snapshot in bytes.
fs_used – The current file system occupancy in bytes.
dev_size – The origin device size in bytes.
- Returns
A SizePolicy object configured for the specified size.
-
property
size
¶ Return the backing store size for a snapshot based on the policy configuration.
-
-
class
snapm.
SizePolicyType
(value)[source]¶ Bases:
enum.Enum
Enum class representing the possible snapshot size policies.
-
FIXED
= 'FIXED'¶
-
PERCENT_FREE
= 'FREE'¶
-
PERCENT_SIZE
= 'SIZE'¶
-
PERCENT_USED
= 'USED'¶
-
-
class
snapm.
SnapStatus
(value)[source]¶ Bases:
enum.Enum
Enum class representing snapshot status: Active, Inactive, Invalid or Reverting.
-
ACTIVE
= 1¶
-
INACTIVE
= 2¶
-
INVALID
= 3¶
-
REVERTING
= 4¶
-
-
exception
snapm.
SnapmBusyError
[source]¶ Bases:
snapm._snapm.SnapmError
A resouce needed by the current command is already in use: for e.g. a snapshot merge is in progress for a previous snapshot set.
-
exception
snapm.
SnapmCalloutError
[source]¶ Bases:
snapm._snapm.SnapmError
An error calling out to an external program.
-
exception
snapm.
SnapmExistsError
[source]¶ Bases:
snapm._snapm.SnapmError
The named snapshot set already exists.
-
exception
snapm.
SnapmInvalidIdentifierError
[source]¶ Bases:
snapm._snapm.SnapmError
An invalid identifier was given.
-
class
snapm.
SnapmLogger
(name, level=0)[source]¶ Bases:
logging.Logger
Snapm logging wrapper class: wrap the Logger.debug() method to allow filtering of submodule debug messages by log mask.
-
debug_masked
(msg, *args, **kwargs)[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:
snapm._snapm.SnapmError
No snapshot provider plugin was found.
-
exception
snapm.
SnapmNoSpaceError
[source]¶ Bases:
snapm._snapm.SnapmError
Insufficient space is available for the requested operation.
-
exception
snapm.
SnapmNotFoundError
[source]¶ Bases:
snapm._snapm.SnapmError
The requested object does not exist.
-
exception
snapm.
SnapmParseError
[source]¶ Bases:
snapm._snapm.SnapmError
An error parsing user input.
-
exception
snapm.
SnapmPathError
[source]¶ Bases:
snapm._snapm.SnapmError
An invalid path was supplied, for example attempting to snapshot something that is not a mount point.
-
exception
snapm.
SnapmPluginError
[source]¶ Bases:
snapm._snapm.SnapmError
An error performing an action via a plugin.
-
exception
snapm.
SnapmStateError
[source]¶ Bases:
snapm._snapm.SnapmError
The status of an object does not allow an operation to proceed.
-
class
snapm.
Snapshot
(name, snapset_name, origin, timestamp, mount_point, provider)[source]¶ Bases:
object
Base class for individual snapshots. Each snapshot plugin should subclass
Snapshot
to provide a specific implementation.-
__init__
(name, snapset_name, origin, timestamp, mount_point, provider)[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.
-
__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
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.
-
set_autoactivate
(auto=False)[source]¶ Set the autoactivation state of this snapshot.
- Parameters
auto –
True
to enable autoactivation orFalse
otherwise.
-
property
size
¶ The size of this snapshot in bytes. For snapshots with fixed-size backstores this reflects the size of the backstore. For snapshots that dynamically allocate space to the snapshot it reflects the device or volume size.
-
property
snapset_name
¶ The name of the snapshot set this snapshot belongs to.
-
property
snapshot_mounted
¶ Test whether the snapshot volume for this
Snapshot
is currently mounted and in use.- Returns
True
if this snaphot is currently mounted orFalse
otherwise.
-
property
snapshot_set
¶ The
SnapshotSet
this snapshot belongs to.
-
property
status
¶ The status of this snapshot. Returns a
SnapStatus
enum value representing the current state of the snapshot.
-
property
time
¶ The human readable timestamp of this snapshot.
-
property
timestamp
¶ The numerical timestamp of this snapshot.
-
property
uuid
¶ The UUID of this snapshot.
-
-
class
snapm.
SnapshotSet
(name, timestamp, snapshots)[source]¶ Bases:
object
Representation of a set of snapshots taken at the same point in time and managed as a group.
-
__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.
-
__str__
()[source]¶ Return a string representation of this
SnapshotSet
.- Returns
A multi-line string describing this snapshot set.
-
property
autoactivate
¶ The overall autoactivation status of this snapshot set. Returns
True
if all snapshots within the set have autoactivate enabled orFalse
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.
-
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
.
-
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
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.
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¶
snapm.command module¶
snapm.report module¶
The snapm reporting module contains a set of classes for creating
simple text based tabular reports for a user-defined set of object
types and fields. No restrictions are placed on the types of object
that can be reported: users of the Report
classes may define
additional object types outside the snapm
package and include these
types in reports generated by the module.
The fields displayed in a specific report may be selected from the available set of fields by specifying a simple comma-separated string list of field names (in display order). In addition, custom multi-column sorting is possible using a similar string notation.
The Report
module is closely based on the device-mapper
reporting engine and shares many features and behaviours with device
mapper reports.
-
class
snapm.report.
Field
[source]¶ Bases:
object
A
Field
represents an instance of aFieldType
including its associated data values.-
__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
-
props
= None¶ reference to the FieldProperties describing this field
-
report
= None¶ reference to the containing Report
-
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_string
= None¶ The formatted string to be reported for this field.
-
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
-
sort_value
= None¶ The raw value of this field. Used for sorting.
-
-
class
snapm.report.
FieldProperties
[source]¶ Bases:
object
Properties of a field instance.
-
align
= None¶
-
compact_one
= False¶
-
compacted
= False¶
-
dtype
= None¶
-
field_num
= None¶
-
implicit
= False¶
-
initial_width
= 0¶
-
objtype
= None¶
-
sort_dir
= None¶
-
sort_key
= False¶
-
sort_posn
= None¶
-
width
= 0¶
-
-
class
snapm.report.
FieldType
[source]¶ Bases:
object
The
FieldType
class describes the properties of a field available in aReport
instance.-
__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
-
align
= None¶
-
desc
= None¶
-
dtype
= None¶
-
head
= None¶
-
name
= None¶
-
objtype
= -1¶
-
report_fn
= None¶
-
width
= 8¶
-
-
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.-
__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
.
-
keys_count
= 0¶
-
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.
-
report_output
()[source]¶ Output report data.
Output this report’s data to the configured report file, using the configured output controls and fields.
On success the number of rows output is returned. On error an exception is raised.
- Returns
the number of rows of output written.
- Return type
int
-
report_types
= 0¶
-
-
class
snapm.report.
ReportObjType
[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
.-
__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.
-
data_fn
= None¶
-
desc
= ''¶
-
objtype
= -1¶
-
prefix
= ''¶
-
-
class
snapm.report.
ReportOpts
[source]¶ Bases:
object
Options controlling the formatting and output of a report.
-
__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>
-
aligned
= True¶
-
buffered
= True¶
-
columns
= 0¶
-
columns_as_rows
= False¶
-
field_name_prefix
= None¶
-
headings
= True¶
-
json
= False¶
-
report_file
= None¶
-
separator
= None¶
-
unquoted
= True¶
-
snapm.manager.plugins module¶
Snapshot manager plugin interface.
-
snapm.manager.plugins.
decode_mount_point
(mount_str)[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.