dmpy - python bindings for device-mapper

The dmpy package exposes the interfaces declared in libdevmapper.h to python programs. It implements a native module named dmpy which provides classes and functions for interacting with the device-mapper: most function and parameter names are exactly the same as their libdevmapper counterparts, with the exception that type prefixes like dm_task_ are dropped where the function is a method of a class, for e.g.:

  dm_task_set_name() -> dmpy.DmTask.set_name()

The dmpy project is hosted on GitHub.

Reporting bugs

Bugs can be reported at the GitHub Issue Tracker, or via the dm-devel mailing list.

Building dmpy

To build the module, from the top-level directory, run:

$ python setup.py build

To build the module for a specific version of the python interpreter (either 2 or 3), use the command name provided by your distribution to select the version, for example:

$ python3 setup.py build $ python2.7 setup.py build $ /usr/python2.7/bin/python setup.py build

You can set PYTHONPATH, or just cd into the build directory to load the module:

  # python3
  [...]
  >>> import dmpy as dm
  >>>

Or use the setup.py install command to install the package.

dmpy types

Device-mapper functions are exposed as module functions and class methods. The following dmpy classes are implemented:

• DmCookie Cookie used for UDEV synchronisation (experimental)
• DmError Generic device-mapper error class
• DmTask, Represents a dm_task object and its methods
• DmTimestamp Represents the device-mapper dm_timestamp
• DmInfo A dm_info struct as returned by DM_DEVICE_INFO
• DmStats Represents a dm_stats handle and the objects it contains
• DmStatsRegion Represents one region and the areas it contains.

All of these (except DmInfo and DmStatsRegion) expose a class-name constructor in the module: DmInfo objects can only be constructed by retrieving one from a DmTask object that has executed a DM_DEVICE_INFO ioctl. Similarly, DmStatsRegion objects should only be obtained by accessing the members of a containing DmStats object.`

See the HACKING.md file for information on dmpy internals.

Getting help

All classes, methods, and module functions have an associated __doc__ string, which can be displayed using Python's builtin help():

>>> help(dm.DmTask.get_uuid)
Help on method_descriptor:

get_uuid(...)
    Get the dm device's UUID based on the value of the mangling mode
    set during preceding `DmTask.run()` call.
    
    To force either mangled or unmangled output, set the `mangle` kwarg
    to '1' or '0' respectively.

Examples

• Import dmpy and get the device-mapper versions:

>>> import dmpy as dm
>>> dm.get_library_version()
'1.02.122 (2016-04-09)'
>>> dm.driver_version()
'4.34.0'
>>>

• List all device-mapper devices and their major and minor numbers

>>> import dmpy as dm
>>> dmt = dm.DmTask(dm.DM_DEVICE_LIST)
>>> dmt.run()
>>> for d in dmt.get_names():
...     print("Device: %s (%d, %d)" % d)
...
Device: vg_hex-lv_home (253, 2)
Device: vg_hex-lv_root (253, 0)
Device: souflé (253, 8)
Device: home (253, 15)
Device: vg_hex-lv_images (253, 1)
>>>

• List all target versions

>>> dmt = dm.DmTask(dm.DM_DEVICE_LIST_VERSIONS)
>>> dmt.run()
>>> versions = dmt.get_versions()
>>> for t in versions.keys():
...     v = versions[t]
...     print("%s (%d.%d.%d)" % (t, v[0], v[1], v[2]))
...
thin (1.19.0)
error (1.4.0)
snapshot (1.15.0)
snapshot-merge (1.4.0)
crypt (1.14.1)
snapshot-origin (1.9.0)
thin-pool (1.19.0)
striped (1.5.1)
mirror (1.14.0)
linear (1.2.1)
zero (1.1.0)

• Send a DM_DEVICE_TARGET_MSG and retrieve the response

>>> dmt = dm.DmTask(dm.DM_DEVICE_TARGET_MSG)
>>> dmt.set_name("vg_hex/lv_root")
>>> dmt.set_message("@stats_list")
<dmpy.DmTask object at 0x7f8de2a21f30>
>>> dmt.set_sector(0)
True
>>> dmt.run()
>>> print(dmt.get_message_response().strip())
0: 0+16777216 16777216 dmioscope -
1: 16777216+16777216 16777216 dmioscope -
2: 33554432+16777216 16777216 dmioscope -
3: 50331648+16777216 16777216 dmioscope -
4: 0+16777216 16777216 dmioscope -
5: 0+67108864 67108864 dmstats -
9: 16777216+16777216 16777216 dmioscope -
10: 33554432+16777216 16777216 dmioscope -
11: 50331648+16777216 16777216 dmioscope -
>>>