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]¶
- __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.SnapStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Bases:
Enum
Enum class representing snapshot status: Active, Inactive or Invalid.
- ACTIVE = 1¶
- INACTIVE = 2¶
- INVALID = 3¶
- exception snapm.SnapmCalloutError[source]¶
Bases:
SnapmError
An error calling out to an external program.
- exception snapm.SnapmError[source]¶
Bases:
Exception
Base class for snapshot manager errors.
- __annotations__ = {}¶
- exception snapm.SnapmExistsError[source]¶
Bases:
SnapmError
The named snapshot set already exists.
- __annotations__ = {}¶
- exception snapm.SnapmInvalidIdentifierError[source]¶
Bases:
SnapmError
An invalid identifier was given.
- __annotations__ = {}¶
- 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.
- 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__ = {}¶
- exception snapm.SnapmNoSpaceError[source]¶
Bases:
SnapmError
Insufficient space is available for the requested operation.
- __annotations__ = {}¶
- exception snapm.SnapmNotFoundError[source]¶
Bases:
SnapmError
The requested object does not exist.
- __annotations__ = {}¶
- exception snapm.SnapmPathError[source]¶
Bases:
SnapmError
An invalid path was supplied, for example attempting to snapshot something that is not a mount point.
- __annotations__ = {}¶
- 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.
- property devpath¶
The device path for this snapshot.
- property mount_point¶
The mount point of this snapshot.
- property name¶
The name of this snapshot.
- property origin¶
The origin of this snapshot.
- property origin_options¶
File system options needed to specify the origin of this snapshot.
- property provider¶
The name of the plugin managing this snapshot.
- rename(new_name)[source]¶
Rename a snapshot within a snapshot set.
- Parameters:
new_name – The new name for the snapshot.
- rollback()[source]¶
Request to roll back 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 snapset_name¶
The name of the snapshot set this snapshot belongs to.
- 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.
- property mount_points¶
The list of mount points in this snapshot set.
- property name¶
The name of this snapshot set.
- property nr_snapshots¶
The number of snapshots in this snapshot set.
- 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 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.
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_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 he
fields
argument must contain a list ofField
objects describing the required report.- __init__(types, fields, output_fields, opts, sort_keys, private)[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¶
- private = 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, 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¶
- 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.