Python bindings for device-mapper
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dmpy
tests
.gitignore
HACKING.md
LICENSE
README.md
setup.py

README.md

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

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