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

The CIM element may be a scalar or an array.

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:

`__repr__`()	Return a representation of the `ValueMapping` object with all attributes, that is suitable for debugging.
`for_method`(server, namespace, classname, ...)	Factory method that returns a new `ValueMapping` instance that maps CIM method return values to the Values qualifier of that method.
`for_parameter`(server, namespace, classname, ...)	Factory method that returns a new `ValueMapping` instance that maps CIM parameter values to the Values qualifier defined on that parameter.
`for_property`(server, namespace, classname, ...)	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`(values_str)	Return the integer value or values for a Values string, based upon this value mapping.
`tovalues`(element_value)	Return the Values string(s) for an element value, based upon this value mapping.

Attributes:

`classname`	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`	Name of the CIM method, that either is mapped itself, or that has the parameter that is mapped.
`namespace`	Name of the CIM namespace containing the class that defines the mapped CIM element.
`parametername`	Name of the CIM parameter that is mapped.
`propname`	Name of the CIM property that is mapped.

__repr__()[source]: Return a representation of the ValueMapping object with all attributes, that is suitable for debugging.

property classname

Name of the CIM class defining the mapped CIM element.

Type: string

property conn: WBEMConnection: Connection to the WBEM server containing the CIM namespace (that contains the mapped CIM element).

property element: CIMProperty, CIMMethod, or CIMParameter: The mapped CIM element.

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.: :raises KeyError: The CIM method does not exist in the CIM class. :raises ModelError: The CIM method is not integer-typed. :raises ValueError: No Values qualifier defined on the CIM method. :raises ModelError: 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.

The CIM parameter may be a scalar or an array.

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.: :raises KeyError: The CIM method does not exist in the CIM class. :raises KeyError: The CIM parameter does not exist in the CIM method. :raises ModelError: The CIM parameter is not integer-typed. :raises ValueError: No Values qualifier defined on the CIM parameter. :raises ModelError: Invalid integer representation in ValueMap qualifier defined on the CIM parameter.

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.

The CIM property may be a scalar or an array.

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.: :raises KeyError: The CIM property does not exist in the CIM class. :raises ModelError: The CIM property is not integer-typed. :raises ValueError: No Values qualifier defined on the CIM property. :raises ModelError: Invalid integer representation in ValueMap qualifier defined on the CIM property.

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.

property methodname

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.

Type: string

property namespace

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

Type: string

property parametername

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

Type: string

property propname

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

Type: string

tobinary(values_str)[source]

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

Due to the complexity of its return value, this method only supports a single Values string at a time. It does support array-typed elements, though. Thus, if multiple Values strings need to be translated, this method must be invoked once for each value to be translated.

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 (single) element value. Must not be None.

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

ValueError – Values string outside of the set defined by Values.
TypeError – Values string is not a string type.

tovalues(element_value)[source]

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

The element value may be a single value or list/tuple of values and the return value will be a single string or list of strings, respectively. An element value of None causes None to be returned.

The passing of array values or scalar values does not need to match whether the element is array-typed or scalar-typed. For example, there may be a need to have the loop through a list of values of an array-typed element on the caller’s side, invoking this method in the loop with a single value. As another example, the method may be used to translate a list of possible values for a scalar-typed element in one call to this method by passing them as a list.

Parameters

element_value (integer or CIMInt or list/tuple thereof) – The value(s) of the CIM element. May be None.

Returns

The Values string(s) for the element value. This is: * a single string, if the element value was a single value * a list of strings, if the element value was a list/tuple of values * None, if the element value was None

Return type

string or list of string

Raises

ValueError – Element value outside of the set defined by ValueMap.
TypeError – Element value is not an integer type.