4.4. Conversion functions
This section describes conversion functions related to CIM objects and CIM data types:
Function |
Purpose |
---|---|
Return the CIM-XML representation of a CIM object or CIM data typed value as an Element object. |
|
Return the CIM-XML representation of a CIM object or CIM data typed value as a unicode string. |
|
Return a CIM data typed value from a Python value. |
|
Return the CIM data type name of a CIM data typed value. |
|
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.
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'
:Objects of type byte string; they will be converted to unicode string.
If type specifies one of the CIM integer data types (e.g.
'uint8'
):If type specifies one of the CIM float data types (e.g.
'real32'
):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'
:string. The string must be an untyped WBEM URI representing an instance path (see DSP0207).
CIMInstanceName
. An instance path.CIMClassName
. A class path.
- 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:
- 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 objectUint8
.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
orCIMInstanceName
).- Raises:
ValueError – Unknown CIM data type name.