4.11. Mapping between ValueMap and Values qualifiers

The ValueMapping class supports translating between the values of an integer-typed CIM element (e.g. property, method, or parameter) that is qualified with the ValueMap and Values qualifiers, and the corresponding values of the Values qualifier, in both directions.

This class supports value ranges (e.g. "4..6") and the unclaimed marker ("..").

class pywbem.ValueMapping[source]

New in pywbem 0.9 as experimental and finalized in 0.10.

A utility class that supports translating between the values of an integer-typed CIM element (property, method, parameter) that is qualified with the ValueMap and Values qualifiers, and the corresponding values of the Values qualifier, in both directions.

This is done by retrieving the CIM class definition defining the CIM element in question, and by inspecting its ValueMap and Values qualifiers.

The translation is performed by the tovalues() and tobinary() methods.

Instances of this class must be created through one of the factory class methods: for_property(), for_method(), or for_parameter().

Value ranges ("2..4") and the indicator for unclaimed values ("..") in the ValueMap qualifier are supported.

All representations of the integer values in the ValueMap qualifier are supported (decimal, binary, octal, hexadecimal), consistent with the definition of the ValueMap qualifier in DSP0004.

Example

Given the following definition of a property in MOF:

class CIM_Foo {

      [ValueMap{ "0", "2..4", "..6", "7..", "9", ".." },
       Values{ "zero", "two-four", "five-six", "seven-eight", "nine",
       "unclaimed"}]
   uint16 MyProp;

};

Assuming this class exists in a WBEM server, the following code will get the class from the server, create a value mapping for this property, and look up the Values strings that correspond to binary property values. This is useful when preparing binary property values for human consumption:

namespace = 'root/cimv2'
conn = pywbem.WBEMConnection(...)  # WBEM server

myprop_vm = pywbem.ValueMapping.for_property(
    conn, namespace, 'CIM_Foo', 'MyProp')

print("Binary value: Values string")
for bin_value in range(0, 12):
    values_str = myprop_vm.tovalues(bin_value)
    print("{0:12}: {1!r}".format(bin_value, values_str))

Resulting output:

Binary value: Values string
           0: 'zero'
           1: 'unclaimed'
           2: 'two-four'
           3: 'two-four'
           4: 'two-four'
           5: 'five-six'
           6: 'five-six'
           7: 'seven-eight'
           8: 'seven-eight'
           9: 'nine'
          10: 'unclaimed'
          11: 'unclaimed'

Translating in the other direction is also of interest, for example when processing values that are provided by humans in terms of the Values strings, or when using the pywbem mock support and the test cases specify property values for CIM instances in terms of the more human-readable Values strings.

Again, assuming the class shown above exists in a WBEM server, the following code will get the class from the server, create a value mapping for this property, and look up the binary property values from the Values strings:

namespace = 'root/cimv2'
conn = pywbem.WBEMConnection(...)  # WBEM server

myprop_vm = pywbem.ValueMapping.for_property(
    conn, namespace, 'CIM_Foo', 'MyProp')

values_strs = ["zero", "two-four", "five-six", "seven-eight", "nine",
               "unclaimed"]

print("Values string: Binary value")
for values_str in values_strs:
    bin_value = myprop_vm.tobinary(values_str)
    print("{0:12}: {1!r}".format(values_str, bin_value))

Resulting output:

Values string: Binary value
       'zero': 0
   'two-four': (2, 4)
   'five-six': (5, 6)
'seven-eight': (7, 8)
       'nine': 9
  'unclaimed': None

Iterating through the pairs of ValueMap and Values entries is also possible. Assuming the class shown above exists in a WBEM server, the following code will get the class from the server, and iterate through the value mapping:

namespace = 'root/cimv2'
conn = pywbem.WBEMConnection(...)  # WBEM server

myprop_vm = pywbem.ValueMapping.for_property(
    conn, namespace, 'CIM_Foo', 'MyProp')

print("Values string: Binary value")
for bin_value, values_str in myprop_vm.items():
    print("{0:12}: {1!r}".format(values_str, bin_value))

Resulting output:

Values string: Binary value
       'zero': 0
   'two-four': (2, 4)
   'five-six': (5, 6)
'seven-eight': (7, 8)
       'nine': 9
  'unclaimed': None

Methods

for_method Factory method that returns a new ValueMapping instance that maps CIM method return values to the Values qualifier of that method.
for_parameter Factory method that returns a new ValueMapping instance that maps CIM parameter values to the Values qualifier defined on that parameter.
for_property Factory method that returns a new ValueMapping instance that maps CIM property values to the Values qualifier defined on that property.
items Generator that iterates through the items of the value mapping.
tobinary Return the integer value or values for a Values string, based upon this value mapping.
tovalues Return the Values string for an element value, based upon this value mapping.

Attributes

classname string – Name of the CIM class defining the mapped CIM element.
conn WBEMConnection – Connection to the WBEM server containing the CIM namespace (that contains the mapped CIM element).
element CIMProperty, CIMMethod, or CIMParameter – The mapped CIM element.
methodname string – Name of the CIM method, that either is mapped itself, or that has the parameter that is mapped.
namespace string – Name of the CIM namespace containing the class that defines the mapped CIM element.
parametername string – Name of the CIM parameter that is mapped.
propname string – Name of the CIM property that is mapped.

Details

classmethod for_property(server, namespace, classname, propname)[source]

Factory method that returns a new ValueMapping instance that maps CIM property values to the Values qualifier defined on that property.

If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).

Parameters:
  • server (WBEMConnection or WBEMServer) – The connection to the WBEM server containing the namespace.
  • namespace (string) – Name of the CIM namespace containing the class. If None, the default namespace of the connection will be used.
  • classname (string) – Name of the CIM class exposing the property. The property can be defined in that class or inherited into that class.
  • propname (string) – Name of the CIM property that defines the Values / ValueMap qualifiers.
Returns:

The new ValueMapping instance.

Raises:
  • Exceptions raised by WBEMConnection.
  • KeyError – The CIM property does not exist in the CIM class.
  • TypeError – The CIM property is not integer-typed.
  • ValueError – No Values qualifier defined on the CIM property.
  • ValueError – Invalid integer representation in ValueMap qualifier defined on the CIM property.
classmethod for_method(server, namespace, classname, methodname)[source]

Factory method that returns a new ValueMapping instance that maps CIM method return values to the Values qualifier of that method.

If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).

Parameters:
  • server (WBEMConnection or WBEMServer) – The connection to the WBEM server containing the namespace.
  • namespace (string) – Name of the CIM namespace containing the class.
  • classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
  • methodname (string) – Name of the CIM method that defines the Values / ValueMap qualifiers.
Returns:

The new ValueMapping instance.

Raises:
  • Exceptions raised by WBEMConnection.
  • KeyError – The CIM method does not exist in the CIM class.
  • TypeError – The CIM method is not integer-typed.
  • ValueError – No Values qualifier defined on the CIM method.
  • ValueError – Invalid integer representation in ValueMap qualifier defined on the CIM method.
classmethod for_parameter(server, namespace, classname, methodname, parametername)[source]

Factory method that returns a new ValueMapping instance that maps CIM parameter values to the Values qualifier defined on that parameter.

If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).

Parameters:
  • server (WBEMConnection or WBEMServer) – The connection to the WBEM server containing the namespace.
  • namespace (string) – Name of the CIM namespace containing the class.
  • classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
  • methodname (string) – Name of the CIM method that has the parameter.
  • parametername (string) – Name of the CIM parameter that defines the Values / ValueMap qualifiers.
Returns:

The new ValueMapping instance.

Raises:
  • Exceptions raised by WBEMConnection.
  • KeyError – The CIM method does not exist in the CIM class.
  • KeyError – The CIM parameter does not exist in the CIM method.
  • TypeError – The CIM parameter is not integer-typed.
  • ValueError – No Values qualifier defined on the CIM parameter.
  • ValueError – Invalid integer representation in ValueMap qualifier defined on the CIM parameter.
__repr__()[source]

Return a representation of the ValueMapping object with all attributes, that is suitable for debugging.

conn

WBEMConnection – Connection to the WBEM server containing the CIM namespace (that contains the mapped CIM element).

namespace

string – Name of the CIM namespace containing the class that defines the mapped CIM element.

classname

string – Name of the CIM class defining the mapped CIM element.

propname

string – Name of the CIM property that is mapped. None, if no property is mapped.

methodname

string – Name of the CIM method, that either is mapped itself, or that has the parameter that is mapped. None, if no method or parameter is mapped.

parametername

string – Name of the CIM parameter that is mapped. None, if no parameter is mapped.

element

CIMProperty, CIMMethod, or CIMParameter – The mapped CIM element.

tovalues(element_value)[source]

Return the Values string for an element value, based upon this value mapping.

Parameters:

element_value (integer or CIMInt) – The value of the CIM element (property, method, parameter).

Returns:

The Values string for the element value.

Return type:

string

Raises:
  • ValueError – Element value outside of the set defined by ValueMap.
  • TypeError – Element value is not an integer type.
tobinary(values_str)[source]

Return the integer value or values for a Values string, based upon this value mapping.

Any returned integer value is represented as the CIM type of the element (e.g. Uint16).

If the Values string corresponds to a single value, that single value is returned as an integer.

If the Values string corresponds to a value range (e.g. “1..” or “..2” or “3..4”), that value range is returned as a tuple with two items that are the lowest and the highest value of the range. That is the case also when the value range is open on the left side or right side.

If the Values string corresponds to the unclaimed indicator “..”, None is returned.

Parameters:

values_str (string) – The Values string for the element value.

Returns:

The element value or value range corresponding to the Values string, or None for unclaimed.

Return type:

CIMInt or tuple of CIMInt or None

Raises:
  • ValueErrorValues string outside of the set defined by Values.
  • TypeErrorValues string is not a string type.
items()[source]

Generator that iterates through the items of the value mapping. The items are the array entries of the Values and ValueMap qualifiers, and they are iterated in the order specified in the arrays. If the ValueMap qualifier is not specified, the default of consecutive integers starting at 0 is used as a default, consistent with DSP0004.

Each iterated item is a tuple of integer value(s) representing the ValueMap array entry, and the corresponding Values string. Any integer value in the iterated items is represented as the CIM type of the element (e.g. Uint16).

If the Values string corresponds to a single element value, the first tuple item is that single integer value.

If the Values string corresponds to a value range (e.g. “1..” or “..2” or “3..4”), that value range is returned as a tuple with two items that are the lowest and the highest value of the range. That is the case also when the value range is open on the left side or right side.

If the Values string corresponds to the unclaimed indicator “..”, the first tuple item is None.

Returns:iterator for tuple of integer value(s) and Values string.