4.4. Conversion functions

This section describes conversion functions related to CIM objects and CIM data types:

Function

Purpose

tocimxml()

Return the CIM-XML representation of a CIM object or CIM data typed value as an Element object.

tocimxmlstr()

Return the CIM-XML representation of a CIM object or CIM data typed value as a unicode string.

cimvalue()

Return a CIM data typed value from a Python value.

cimtype()

Return the CIM data type name of a CIM data typed value.

type_from_name()

Return the Python type object for a CIM data type name.

pywbem.tocimxml(value)[source]

Return the CIM-XML representation of the input object, as an object of an appropriate subclass of Element.

The returned CIM-XML representation is consistent with DSP0201.

Parameters:

value (CIM object, CIM data type, number, datetime.datetime, or tuple/list thereof) – The input object. Must not be None.

Returns:

The CIM-XML representation, as an object of an appropriate subclass of Element.

Raises:

ValueError – Invalid input value.

pywbem.tocimxmlstr(value, indent=None)[source]

Return the CIM-XML representation of the CIM object or CIM data type, as a unicode string.

New in pywbem 0.9.

The returned CIM-XML representation is consistent with DSP0201.

Parameters:
  • value (CIM object or CIM data type or Element) – The CIM object or CIM data type to be converted to CIM-XML, or an Element object that already is the CIM-XML representation.

  • indent (string or integer) –

    None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.

    Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.

Returns:

The CIM-XML representation of the value, as a unicode string.

pywbem.cimvalue(value, type)[source]

Return a CIM data type representing the specified value in the specified CIM type.

New in pywbem 0.12.

This function guarantees that the returned object is a valid CIM data type. If the input parameters are not sufficient to construct a CIM data type, an exception is raised.

If the provided value is already a CIM data type (or None), the input value is returned.

Otherwise, the value is converted to a CIM data type as described below.

If the provided value is a list, a new list is returned with this function being invoked recursively on the items of the input list.

Embedded objects and embedded instances are not handled by this function.

Parameters:
  • type (string) –

    The CIM data type name for the CIM object. See CIM data types for valid type names.

    If value is a list, type must specify the CIM data type name of an item in the list.

  • value (CIM data type and other suitable types) –

    The value to be represented as a CIM object.

    If None, the returned object will be None.

    The following other suitable types are supported (in addition to the respective CIM data type):

    • If type is 'string' or 'char16':

    • If type specifies one of the CIM integer data types (e.g. 'uint8'):

      • Any object supported as an init parameter for int or long (Python 2 only). This includes string values with decimal integer numbers. If the value is not supported, ValueError will be raised.

    • If type specifies one of the CIM float data types (e.g. 'real32'):

      • Any object supported as an init parameter for float. This includes string values with decimal integer or float numbers. If the value is not supported, ValueError will be raised.

    • If type is 'boolean':

      • Any object. The value is converted to bool using the standard Python truth testing procedure.

    • If type is 'datetime':

      • Any object supported as an init parameter for CIMDateTime .

    • If type is 'reference':

Returns:

A CIM data type object, representing the specified value and type.

Raises:
  • ValueError – An input parameter has an invalid value.

  • TypeError – An input parameter has an invalid Python type.

pywbem.cimtype(obj)[source]

Return the CIM data type name of a CIM typed object, as a string.

For an array, the type is determined from the first array element (CIM arrays must be homogeneous w.r.t. the type of their elements). If the array is empty, that is not possible and ValueError is raised.

Note that Python numbers are not valid input objects because determining their CIM data type (e.g. Uint8, Real32) would require knowing the value range. Therefore, TypeError is raised in this case.

Parameters:

obj (CIM data type) – The object whose CIM data type name is returned.

Returns:

The CIM data type name of the object (e.g. "uint8").

Return type:

string

Raises:
  • TypeError – The object does not have a valid CIM data type.

  • ValueError – Cannot determine CIM data type from an empty array.

pywbem.type_from_name(type_name)[source]

Return the Python type object for a given CIM data type name.

For example, type name "uint8" will return type object Uint8.

For CIM data type names "string" and "char16", the unicode string type is returned (Unicode strings are the preferred representation for these CIM data types).

The returned type can be used as a constructor from a differently typed input value in many cases. Notable limitations are:

  • In Python 3, the str type is used to represent CIM string data types. When constructing such an object from a byte string, the resulting string is not a unicode-translated version of the byte string as one would assume (and as is the case in Python 2), but instead that results in a unicode string that is a repr() representation of the byte string:

    string_type = type_from_name('string')  # str
    s1 = b'abc'
    s2 = string_type(s1)  # results in u"b'abc'", and not in u"abc"
    

    Use decode() and encode() for strings instead of type conversion syntax (in both Python 2 and 3, for consistency).

  • For CIM type “reference”, type object CIMInstanceName is returned, even though for use in CIM method parameters, CIMClassName is also valid.

Parameters:

type_name (string) – The simple (=non-array) CIM data type name (e.g. "uint8" or "reference").

Returns:

The Python type object for the CIM data type (e.g. Uint8 or CIMInstanceName).

Raises:

ValueError – Unknown CIM data type name.