Pywbem - A WBEM client and related utilities, written in pure Python

Raises

TypeError – Invalid type in keybindings
ValueError – Invalid format argument

tocimxml(ignore_host=False, ignore_namespace=False)[source]

Return the CIM-XML representation of this CIM instance path, as an object of an appropriate subclass of Element.

If the instance path has no namespace specified or if ignore_namespace is True, the returned CIM-XML representation is an INSTANCENAME element consistent with DSP0201.

Otherwise, if the instance path has no host specified or if ignore_host is True, the returned CIM-XML representation is a LOCALINSTANCEPATH element consistent with DSP0201.

Otherwise, the returned CIM-XML representation is a INSTANCEPATH element consistent with DSP0201.

The order of keybindings in the returned CIM-XML representation is preserved from the CIMInstanceName object.

CIMInstanceName objects without keybindings cause a UserWarning to be issued, because this is invalid according to DSP0004 (section 7.7.5).

Parameters

ignore_host (bool) – Ignore the host of the instance path, even if a host is specified.
ignore_namespace (bool) – Ignore the namespace and host of the instance path, even if a namespace and/or host is specified.

Returns

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

tocimxmlstr(indent=None, ignore_host=False, ignore_namespace=False)[source]

Return the CIM-XML representation of this CIM instance path, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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.
ignore_host (bool) – Ignore the host of the instance path, even if a host is specified.
ignore_namespace (bool) – Ignore the namespace and host of the instance path, even if a namespace and/or host is specified.

Returns

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

update(*args, **kwargs)[source]

Update the keybindings of this CIM instance path.

Existing keybindings will be updated, and new keybindings will be added.

Parameters

*args (list) – Keybindings for updating the keybindings of the instance path, specified as positional arguments. Each positional argument must be a tuple (key, value), where key and value are described for setting the keybindings property.
**kwargs (dict) – Keybindings for updating the keybindings of the instance path, specified as keyword arguments. The name and value of the keyword arguments are described as key and value for setting the keybindings property.

values()[source]

Return the keybinding values of this CIM instance path.

The type of the returned object is consistent with the behavior of the corresponding method of the built-in dict class: On Python 2, a list is returned; on Python 3, a dictionary view is returned.

The order of keybindings is preserved.

CIMInstance

class pywbem.CIMInstance(classname, properties=None, qualifiers=None, path=None)[source]

A representation of a CIM instance in a CIM namespace in a WBEM server, optionally including its instance path.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

Parameters

classname (string) –
Name of the creation class for the instance.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
properties (properties input object) –
The property values for the instance.

Deprecated: Providing key property values will cause the corresponding keybindings in the instance path (if set) to be updated accordingly. This behavior has been deprecated in pywbem 1.1.0 and will be removed in a future version of pywbem.
qualifiers (qualifiers input object) –
The qualifiers for the instance.

Note that DSP0200 has deprecated the presence of qualifiers on CIM instances.
path (CIMInstanceName) –
Instance path for the instance.

The provided object will be copied before being stored in the CIMInstance object.

None means that the instance path is unspecified, and the path attribute will also be None.

Raises

ValueError – classname is None, a property or qualifier name is None, or a property or qualifier name does not match its dictionary key.
TypeError – a numeric Python type was used for a property or qualifier value.

Methods:

`__eq__`(other)	Equality test function for two `CIMInstance` objects.
`__hash__`()	Return a hash value based on the same public attributes of this class as used for equality comparison, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM instance, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM instance, for human consumption.
`copy`()	Return a new `CIMInstance` object that is a copy of this CIM instance.
`from_class`(klass[, namespace, ...])	Return a new `CIMInstance` object from specified key property values and from the key property definitions in a class.
`get`(key[, default])	Return the value of a particular property of this CIM instance, or a default value.
`has_key`(key)	Return a boolean indicating whether this CIM instance has a particular property.
`items`()	Return the properties of this CIM instance, where each item is a tuple of property name and value (the `value` attribute of the `CIMProperty` object).
`iteritems`()	Return an iterator through the properties of this CIM instance, where each item is a tuple of property name and value.
`iterkeys`()	Return an iterator through the property names of this CIM instance.
`itervalues`()	Return an iterator through the property values of this CIM instance.
`keys`()	Return the property names of this CIM instance.
`tocimxml`([ignore_path])	Return the CIM-XML representation of this CIM instance, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent, ignore_path])	Return the CIM-XML representation of this CIM instance, as a unicode string.
`tomof`([maxline])	Return a MOF string with the specification of this CIM instance.
`update`(args, *kwargs)	Update the properties of this CIM instance.
`update_existing`(args, *kwargs)	Update the values of already existing properties of this CIM instance.
`values`()	Return the property values (the `value` attribute of the `CIMProperty` object) of this CIM instance.

Attributes:

`classname`	Name of the creation class of this CIM instance.
`path`	Instance path of this CIM instance.
`properties`	Properties of this CIM instance.
`qualifiers`	Qualifiers (qualifier values) of this CIM instance.

__eq__(other)[source]

Equality test function for two CIMInstance objects.

The equality is based on some of their public attributes:

classname
path
properties
qualifiers

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMInstance object.

__hash__()[source]: Return a hash value based on the same public attributes of this class as used for equality comparison, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]

Return a string representation of this CIM instance, that is suitable for debugging.

The properties and qualifiers will be ordered by their names in the result.

__str__()[source]: Return a short string representation of this CIM instance, for human consumption.

property classname

Name of the creation class of this CIM instance.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

copy()[source]

Return a new CIMInstance object that is a copy of this CIM instance.

This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:

The CIMProperty objects in the properties dictionary (but not the dictionary object itself)
The CIMQualifier objects in the qualifiers dictionary (but not the dictionary object itself)

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

static from_class(klass, namespace=None, property_values=None, include_missing_properties=True, include_path=True, include_class_origin=False)[source]

Return a new CIMInstance object from specified key property values and from the key property definitions in a class.

The properties in the returned instance do not have any qualifiers.

Parameters

klass (CIMClass) – CIM class from which the instance will be constructed. This class must include qualifiers and should include properties from any superclasses in the model insure it includes all properties that are to be built into the instance, in particular any key properties if the include_path parameter is True.
namespace (string) – Namespace to be included in the path component of the returned CIMInstance if include_path parameter is True.
property_values (dict or NocaseDict) – Dictionary containing name/value pairs where the names are the names of properties in the class and the properties are the property values to be set into the instance properties. The values must match the type defined for the property in the class. If a property is in the property_values dictionary but not in the class a ValueError exception is raised. Not all properties in the class need to be defined in property_values.
include_missing_properties –
Determines if properties not in the property_values parameter are included in the instance.

If True all properties from the class are included in the new instance including those not defined in property_values parameter with with the default value defined in the class if one is defined, or otherwise None”.

If False only properties in the property_values parameter are included in the new instance.

Returns

A CIM instance created from klass and property_values parameters with the defined properties and optionally the path component set.

No qualifiers are included in the returned instance and the existence of the class origin attribute depends on the include_class_origin parameter.

All other attributes of each property are the same as the corresponding class property.

Return type

CIMInstance

Raises

ValueError – Conflicts between the class properties and property_values parameter or the instance does not include all key properties defined in the class.
TypeError – Mismatch between types of the property values in property_values parameter and the property type in the corresponding class property

get(key, default=None)[source]

Return the value of a particular property of this CIM instance, or a default value.

New in pywbem 0.8.

Parameters

key (string) – Name of the property (in any lexical case).
default (CIM data type) – Default value that is returned if a property with the specified name does not exist in the instance.

Returns

Value of the property, or the default value.

Return type

CIM data type

has_key(key)[source]

Return a boolean indicating whether this CIM instance has a particular property.

Parameters: key (string) – Name of the property (in any lexical case).
Returns: Boolean indicating whether the instance has the property.
Return type: bool

items()[source]

Return the properties of this CIM instance, where each item is a tuple of property name and value (the value attribute of the CIMProperty object).

The type of the returned object is consistent with the behavior of the corresponding method of the built-in dict class: On Python 2, a list is returned; on Python 3, a dictionary view is returned.

The property names have their original lexical case, and the order of properties is preserved.

iteritems()[source]

Return an iterator through the properties of this CIM instance, where each item is a tuple of property name and value.

The property values are the value attributes of the CIMProperty objects.

The property names have their original lexical case, and the order of properties is preserved.

Deprecated: This method is deprecated on Python 3 and will be removed in a future version of pywbem, consistent with the built-in dict class on Python 3. Use the items() method instead.

iterkeys()[source]

Return an iterator through the property names of this CIM instance.

The property names have their original lexical case, and the order of properties is preserved.

Deprecated: This method is deprecated on Python 3 and will be removed in a future version of pywbem, consistent with the built-in dict class on Python 3. Use the keys() method instead.

itervalues()[source]

Return an iterator through the property values of this CIM instance.

The property values are the value attributes of the CIMProperty objects.

The order of properties is preserved.

Deprecated: This method is deprecated on Python 3 and will be removed in a future version of pywbem, consistent with the built-in dict class on Python 3. Use the values() method instead.

keys()[source]

Return the property names of this CIM instance.

The type of the returned object is consistent with the behavior of the corresponding method of the built-in dict class: On Python 2, a list is returned; on Python 3, a dictionary view is returned.

The property names have their original lexical case, and the order of properties is preserved.

property path

Instance path of this CIM instance.

None means that the instance path is unspecified.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: CIMInstanceName

property properties

Properties of this CIM instance.

Will not be None.

Each dictionary item specifies one property value, with:

key (unicode string): Property name. Its lexical case was preserved.
value (CIMProperty): Property value.

The order of properties in the CIM instance is preserved.

This attribute is settable; setting it will cause the current CIM properties to be replaced with the new properties.

Deprecated: Updating a key property will cause the corresponding keybinding in the instance path (if set) to be updated accordingly. This behavior has been deprecated in pywbem 1.1.0 and will be removed in a future version of pywbem.

For details, see the description of the same-named init parameter. Note that the property value may be specified as a CIM data type or as a CIMProperty object.

The CIM property values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. In that case, the provided input value must be a CIMProperty object. A corresponding keybinding in the instance path (if set) will not (!) be updated in this case:

inst = CIMInstance(...)
p1 = CIMProperty('p1', ...)  # must be CIMProperty

inst.properties['p1'] = p1  # Set "p1" to p1 (add if needed)
p1 = inst.properties['p1']  # Access "p1"
del inst.properties['p1']  # Delete "p1" from the instance

In addition, the CIM properties can be accessed and manipulated one by one by using the entire CIMInstance object like a dictionary. In that case, the provided input value may be specified as a CIM data type or as a CIMProperty object:

inst = CIMInstance(...)
p2 = Uint32(...)  # may be CIM data type or CIMProperty

inst['p2'] = p2  # Set "p2" to p2 (add if needed)
p2 = inst['p2']  # Access "p2"
del inst['p2']  # Delete "p2" from the instance

Type: NocaseDict

property qualifiers

Qualifiers (qualifier values) of this CIM instance.

Will not be None.

Each dictionary item specifies one qualifier value, with:

key (unicode string): Qualifier name. Its lexical case was preserved.
value (CIMQualifier): Qualifier value.

The order of qualifiers in the CIM instance is preserved.

This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of this class.

The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary.

Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.

Type: NocaseDict

tocimxml(ignore_path=False)[source]

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

If the instance has no instance path specified or if ignore_path is True, the returned CIM-XML representation is an INSTANCE element consistent with DSP0201. This is the required element for representing embedded instances.

Otherwise, if the instance path of the instance has no namespace specified, the returned CIM-XML representation is an VALUE.NAMEDINSTANCE element consistent with DSP0201.

Otherwise, if the instance path of the instance has no host specified, the returned CIM-XML representation is a VALUE.OBJECTWITHLOCALPATH element consistent with DSP0201.

Otherwise, the returned CIM-XML representation is a VALUE.INSTANCEWITHPATH element consistent with DSP0201.

The order of properties and qualifiers in the returned CIM-XML representation is preserved from the CIMInstance object.

Parameters: ignore_path (bool) – Ignore the path of the instance, even if a path is specified.
Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.

tocimxmlstr(indent=None, ignore_path=False)[source]

Return the CIM-XML representation of this CIM instance, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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.
ignore_path (bool) – Ignore the path of the instance, even if a path is specified.

Returns

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

tomof(maxline=80)[source]

Return a MOF string with the specification of this CIM instance.

The returned MOF string conforms to the instanceDeclaration ABNF rule defined in DSP0004, with the following limitations:

Pywbem does not support instance aliases, so the returned MOF string does not define an alias name for the instance.
Even though pywbem supports qualifiers on CIMInstance objects, and on CIMProperty objects that are used as property values within an instance, the returned MOF string does not contain any qualifier values on the instance or on its property values.

The order of properties and qualifiers is preserved.

Parameters: maxline (integer) – Maximum line length.
Returns: MOF string.
Return type: unicode string

update(*args, **kwargs)[source]

Update the properties of this CIM instance.

Existing properties will be updated, and new properties will be added.

Parameters

*args (list) – Properties for updating the properties of the instance, specified as positional arguments. Each positional argument must be a tuple (key, value), where key and value are described for setting the properties property.
**kwargs (dict) – Properties for updating the properties of the instance, specified as keyword arguments. The name and value of the keyword arguments are described as key and value for setting the properties property.

update_existing(*args, **kwargs)[source]

Update the values of already existing properties of this CIM instance.

From the specified new properties, only properties that already exist in the instance will be updated. New properties will not be added to the instance; they will be ignored without further notice.

Parameters

*args (list) –
New properties, specified as positional arguments. Each positional argument must be one of:
- an iterable of tuple (name, value), where each tuple specifies the name of the property to be updated and its new value.
- an object with an items() method that iterates through tuple (name, value), where each tuple specifies the name of the property to be updated and its new value.
  
  Examples of such objects are CIMInstanceName (where its keybindings will be used as new properties) or CIMInstance (where its properties will be used as new properties).
**kwargs (dict) – New properties, specified as keyword arguments. Each keyword argument specifies one new property, where the argument name is the name of the property to be updated and the argument value is its new value.

values()[source]

Return the property values (the value attribute of the CIMProperty object) of this CIM instance.

The type of the returned object is consistent with the behavior of the corresponding method of the built-in dict class: On Python 2, a list is returned; on Python 3, a dictionary view is returned.

The order of properties is preserved.

CIMClassName

class pywbem.CIMClassName(classname, host=None, namespace=None)[source]

A CIM class path (aka CIM class name).

A CIM class path references a CIM class in a CIM namespace in a WBEM server. Namespace and WBEM server may be unspecified.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

Parameters

classname (string) –
Class name of the referenced class.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
host (string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced class.

The format of the string must be:

host[:port]

The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986 with the extensions for zone identifiers as defined in RFC6874, supporting - (minus) for the delimiter before the zone ID string, as an additional choice to %25.
None means that the WBEM server is unspecified, and the host attribute will also be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
namespace (string) –
Name of the CIM namespace containing the referenced class.

None means that the namespace is unspecified, and the namespace attribute will also be None.

Leading and trailing slash characters will be stripped. The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.

Raises

ValueError – classname is None.

Methods:

`__eq__`(other)	Equality test function for two `CIMClassName` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM class path, that is suitable for debugging.
`__str__`()	Return a WBEM URI string of this CIM class path.
`copy`()	Return a new `CIMClassName` object that is a copy of this CIM class path.
`from_wbem_uri`(wbem_uri)	Return a new `CIMClassName` object from the specified WBEM URI string.
`to_wbem_uri`([format])	Return the (untyped) WBEM URI string of this CIM class path.
`tocimxml`([ignore_host, ignore_namespace])	Return the CIM-XML representation of this CIM class path, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent, ignore_host, ...])	Return the CIM-XML representation of this CIM class path, as a unicode string.

Attributes:

`classname`	Class name of this CIM class path, identifying the referenced class.
`host`	Host and optionally port of this CIM class path, identifying the WBEM server of the referenced class.
`namespace`	Namespace name of this CIM class path, identifying the namespace of the referenced class.

__eq__(other)[source]

Equality test function for two CIMClassName objects.

The equality is based on their public attributes:

host
namespace
classname

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMClassName object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]: Return a string representation of this CIM class path, that is suitable for debugging.

__str__()[source]

Return a WBEM URI string of this CIM class path.

The returned WBEM URI string is in the historical format returned by to_wbem_uri().

For new code, it is recommended that the standard format is used; it is returned by to_wbem_uri() as the default format.

If you want to access the class name, use the classname attribute, instead of relying on the coincidence that the historical format of a WBEM URI without host and namespace happens to be the class name.

Examples (for the historical format):

With host and namespace:

//acme.com/cimv2/test:CIM_RegisteredProfile

Without host but with namespace:
```
cimv2/test:CIM_RegisteredProfile
```
Without host and without namespace:
```
CIM_RegisteredProfile
```

property classname

Class name of this CIM class path, identifying the referenced class.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

copy()[source]

Return a new CIMClassName object that is a copy of this CIM class path.

Objects of this class have no mutable types in any attributes, so modifications of the original object will not affect the returned copy, and vice versa.

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

static from_wbem_uri(wbem_uri)[source]

Return a new CIMClassName object from the specified WBEM URI string.

New in pywbem 0.12.

The WBEM URI string must be a CIM class path in untyped WBEM URI format, as defined in DSP0207, with these extensions:

DSP0207 restricts the namespace types (URI schemes) to be one of http, https, cimxml-wbem, or cimxml-wbems. Pywbem tolerates any namespace type, but issues a UserWarning if it is not one of the namespace types defined in DSP0207.
DSP0207 requires a slash before the namespace name. For local WBEM URIs (no namespace type, no authority), that slash is the first character of the WBEM URI. For historical reasons, pywbem tolerates a missing leading slash for local WBEM URIs. Note that pywbem requires the slash (consistent with DSP0207) when the WBEM URI is not local.
DSP0207 requires a colon before the class name. For historical reasons, pywbem tolerates a missing colon before the class name, if it would have been the first character of the string.

CIM class paths in the typed WBEM URI format defined in DSP0207 are not supported.

Examples:

https://jdd:test@acme.com:5989/cimv2/test:CIM_RegisteredProfile
http://acme.com/root/cimv2:CIM_ComputerSystem
http:/root/cimv2:CIM_ComputerSystem
/root/cimv2:CIM_ComputerSystem
root/cimv2:CIM_ComputerSystem
/:CIM_ComputerSystem
:CIM_ComputerSystem
CIM_ComputerSystem

Parameters: wbem_uri (string) – WBEM URI for a class path.
Returns: The class path created from the specified WBEM URI string.
Return type: CIMClassName
Raises: ValueError – Invalid WBEM URI format for a class path. This includes typed WBEM URIs.

property host

Host and optionally port of this CIM class path, identifying the WBEM server of the referenced class.

For details about the string format, see the same-named init parameter of this class.

None means that the host and port are unspecified.

This attribute is settable. For details, see the description of the same-named init parameter.

Type: unicode string

property namespace

Namespace name of this CIM class path, identifying the namespace of the referenced class.

None means that the namespace is unspecified.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

to_wbem_uri(format='standard')[source]

Return the (untyped) WBEM URI string of this CIM class path.

The returned WBEM URI contains its components as follows:

it does not contain a namespace type (URI scheme).
it contains an authority (host) component according to the host attribute, if that is not None. Otherwise, it does not contain the authority component.
it contains a namespace component according to the namespace attribute, if that is not None. Otherwise, it does not contain the namespace component.
it contains a class name component according to the classname attribute.

Note that when you do not want some of these components to show up in the resulting WBEM URI string, you can set them to None before calling this method.

Except when using the format “canonical”, this method should not be used to compare class paths for equality: DSP0004 defines several components of a class path to be compared case insensitively. All WBEM URI formats returned by this method except for the format “canonical” return a WBEM URI string that preserves the lexical case of any components. Therefore, two class paths that are considered equal according to DSP0004 may not have equal WBEM URI strings as as returned by this method.

Instead, equality of class paths represented by CIMClassName objects should be determined by using the == operator, which performs the comparison conformant to DSP0004. If you have WBEM URI strings without the corresponding CIMClassName object, such an object can be created by using the static method from_wbem_uri().

Parameters

format (string) –

Format for the generated WBEM URI string, using one of the following values:

"standard" - Standard format that is conformant to untyped WBEM URIs for class paths defined in DSP0207.
"canonical" - Like "standard", except that the following items have been converted to lower case: host, namespace, and classname. This format guarantees that two class paths that are considered equal according to DSP0004 result in equal WBEM URI strings. Therefore, the returned WBEM URI is suitable to be used as a key in dictionaries of CIM classes.
"cimobject" - Format for the CIMObject header field in CIM-XML messages for representing class paths (used internally, see DSP0200).
"historical" - Historical format for WBEM URIs (used by __str__(); should not be used by new code). The historical format has the following differences to the standard format:
- If the host component is not present, the slash after the host is also omitted. In the standard format, that slash is always present.
- If the namespace component is not present, the colon after the namespace is also omitted. In the standard format, that colon is always present.

Examples:

With host and namespace, standard format:

//ACME.com/cimv2/Test:CIM_RegisteredProfile

With host and namespace, canonical format:

//acme.com/cimv2/test:cim_registeredprofile

Without host but with namespace, standard format:
```
/cimv2/Test:CIM_RegisteredProfile
```
Without host but with namespace, canonical format:
```
/cimv2/test:cim_registeredprofile
```
Without host and without namespace, standard format:
```
/:CIM_RegisteredProfile
```

Returns: Untyped WBEM URI of the CIM class path, in the specified format.
Return type: unicode string
Raises: ValueError – Invalid format

tocimxml(ignore_host=False, ignore_namespace=False)[source]

Return the CIM-XML representation of this CIM class path, as an object of an appropriate subclass of Element.

If the class path has no namespace specified or if ignore_namespace is True, the returned CIM-XML representation is a CLASSNAME element consistent with DSP0201.

Otherwise, if the class path has no host specified or if ignore_host is True, the returned CIM-XML representation is a LOCALCLASSPATH element consistent with DSP0201.

Otherwise, the returned CIM-XML representation is a CLASSPATH element consistent with DSP0201.

Parameters

ignore_host (bool) – Ignore the host of the class path, even if a host is specified.
ignore_namespace (bool) – Ignore the namespace and host of the class path, even if a namespace and/or host is specified.

Returns

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

tocimxmlstr(indent=None, ignore_host=False, ignore_namespace=False)[source]

Return the CIM-XML representation of this CIM class path, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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.
ignore_host (bool) – Ignore the host of the class path, even if a host is specified.
ignore_namespace (bool) – Ignore the namespace and host of the class path, even if a namespace and/or host is specified.

Returns

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

CIMClass

class pywbem.CIMClass(classname, properties=None, methods=None, superclass=None, qualifiers=None, path=None)[source]

A representation of a CIM class in a CIM namespace in a WBEM server, optionally including its class path.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

Parameters

classname (string) –
Class name of the class.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
properties (properties input object) – The property declarations for the class.
methods (methods input object) – The method declarations for the class.
superclass (string) –
Name of the superclass for the class.

None means that the class is a top-level class, and the superclass attribute will also be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
qualifiers (qualifiers input object) – The qualifiers for the class.
path (CIMClassName) –
Class path for the class.

New in pywbem 0.11.

The provided object will be copied before being stored in the CIMClass object.

None means that the instance path is unspecified, and the path attribute will also be None.

This parameter has been added in pywbem 0.11 as a convenience for the user in order so that CIMClass objects can be self-contained w.r.t. their class path.

Raises

ValueError – classname is None, a property, method or qualifier name is None, or a property, method or qualifier name does not match its dictionary key.
TypeError – a numeric Python type was used for a qualifier value.

Methods:

`__eq__`(other)	Equality test function for two `CIMClass` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM class, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM class, for human consumption.
`copy`()	Return a new `CIMClass` object that is a copy of this CIM class.
`tocimxml`()	Return the CIM-XML representation of this CIM class, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent])	Return the CIM-XML representation of this CIM class, as a unicode string.
`tomof`([maxline])	Return a MOF string with the declaration of this CIM class.

Attributes:

`classname`	Class name of this CIM class.
`methods`	Methods (declarations) of this CIM class.
`path`	Class path of this CIM class.
`properties`	Properties (declarations) of this CIM class.
`qualifiers`	Qualifiers (qualifier values) of this CIM class.
`superclass`	Class name of the superclass of this CIM class.

__eq__(other)[source]

Equality test function for two CIMClass objects.

The equality is based on their public attributes:

classname
superclass
qualifiers
properties
methods
path

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMClass object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]

Return a string representation of this CIM class, that is suitable for debugging.

The order of properties, method and qualifiers will be preserved in the result.

__str__()[source]: Return a short string representation of this CIM class, for human consumption.

property classname

Class name of this CIM class.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

copy()[source]

Return a new CIMClass object that is a copy of this CIM class.

This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:

The CIMProperty objects in the properties dictionary (but not the dictionary object itself)
The CIMMethod objects in the methods dictionary (but not the dictionary object itself)
The CIMQualifier objects in the qualifiers dictionary (but not the dictionary object itself)

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

property methods

Methods (declarations) of this CIM class.

Will not be None.

Each dictionary item specifies one method, with:

key (unicode string): Method name. Its lexical case was preserved.
value (CIMMethod): Method declaration.

The order of methods in the CIM class is preserved.

This attribute is settable; setting it will cause the current CIM methods to be replaced with the new methods. For details, see the description of the same-named init parameter of this class.

The CIM methods can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be a CIMMethod object:

cls = CIMClass(...)
m1 = CIMMethod('m1', ...)  # must be a CIMMethod

cls.methods['m1'] = m1  # Set "m1" to m1 (add if needed)
m1 = cls.methods['m1']  # Access "m1"
del cls.methods['m1']  # Delete "m1" from the class

Type: NocaseDict

property path

Class path of this CIM class.

New in pywbem 0.11.

None means that the class path is unspecified.

This attribute has been added in pywbem 0.11 as a convenience for the user in order so that CIMClass objects can be self-contained w.r.t. their class path.

This attribute will be set in in any CIMClass objects returned by WBEMConnection methods, based on information in the response from the WBEM server.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: CIMClassName

property properties

Properties (declarations) of this CIM class.

Will not be None.

Each dictionary item specifies one property declaration, with:

key (unicode string): Property name. Its lexical case was preserved.
value (CIMProperty): Property declaration.

The order of properties in the CIM class is preserved.

This attribute is settable; setting it will cause the current CIM properties to be replaced with the new properties. For details, see the description of the same-named init parameter of this class.

The CIM properties can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be a CIMProperty object:

cls = CIMClass(...)
p1 = CIMProperty('p1', ...)  # must be a CIMProperty

cls.properties['p1'] = p1  # Set "p1" to p1 (add if needed)
p1 = cls.properties['p1']  # Access "p1"
del cls.properties['p1']  # Delete "p1" from the class

Type: NocaseDict

property qualifiers

Qualifiers (qualifier values) of this CIM class.

Will not be None.

Each dictionary item specifies one qualifier value, with:

key (unicode string): Qualifier name. Its lexical case was preserved.
value (CIMQualifier): Qualifier value.

The order of qualifiers in the CIM class is preserved.

This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of this class.

The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a CIMQualifier object:

cls = CIMClass(...)
q1 = Uint32(...)  # may be CIM data type or CIMQualifier

cls.qualifiers['q1'] = q1  # Set "q1" to q1 (add if needed)
q1 = cls.qualifiers['q1']  # Access "q1"
del cls.qualifiers['q1']  # Delete "q1" from the class

Type: NocaseDict

property superclass

Class name of the superclass of this CIM class.

None means that the class is a top-level class.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

tocimxml()[source]

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

The returned CIM-XML representation is a CLASS element consistent with DSP0201. This is the required element for representing embedded classes.

If the class has a class path specified, it will be ignored.

The order of properties, methods, parameters, and qualifiers in the returned CIM-XML representation is preserved from the CIMClass object.

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

tocimxmlstr(indent=None)[source]

Return the CIM-XML representation of this CIM class, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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 object, as a unicode string.

tomof(maxline=80)[source]

Return a MOF string with the declaration of this CIM class.

The returned MOF string conforms to the classDeclaration ABNF rule defined in DSP0004.

The order of properties, methods, parameters, and qualifiers is preserved.

The path attribute of this object will not be included in the returned MOF string.

Consistent with that, class path information is not included in the returned MOF string.

Returns: MOF string.
Return type: unicode string

CIMProperty

class pywbem.CIMProperty(name, value, type=None, class_origin=None, array_size=None, propagated=None, is_array=None, reference_class=None, qualifiers=None, embedded_object=None)[source]

A CIM property (value or declaration).

This object can be used in a CIMInstance object for representing a property value, or in a CIMClass object for representing a property declaration.

For property values in CIM instances:

The value attribute is the actual value of the property.

Qualifiers are not allowed.

For property declarations in CIM classes:

The value attribute is the default value of the property declaration.

Qualifiers are allowed.

Scalar (=non-array) properties may have a value of NULL (= None), any primitive CIM data type, reference type, and string type with embedded instance or embedded object.

Array properties may be Null or may have elements with a value of NULL, any primitive CIM data type, and string type with embedded instance or embedded object. Reference types are not allowed in property arrays in CIM, as per DSP0004.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

The init method infers optional parameters that are not specified (for example, it infers type from the Python type of value and other information). If the specified parameters are inconsistent, an exception is raised. If an optional parameter is needed for some reason, an exception is raised.

Parameters

name (string) –
Name of the property.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or other suitable types) –
Value of the property.

The property value is interpreted as an actual property value when the CIM property is used in a CIM instance, and as default value when the CIM property is used in a CIM class.

None means that the property is Null, and the same-named attribute in the CIMProperty object will also be None.

The specified value will be converted to a CIM data type using the rules documented in the description of cimvalue(), taking into account the type parameter.
type (string) –
Name of the CIM data type of the property (e.g. "uint8").

None will cause the type to be inferred from the value parameter, raising ValueError if it cannot be inferred (for example when value is None or a Python integer).

ValueError is raised if the type is not a valid CIM data type (see CIM data types).
class_origin (string) –
The CIM class origin of the property (the name of the most derived class that defines or overrides the property in the class hierarchy of the class owning the property).

None means that class origin information is not available, and class_origin attribute will also be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
array_size (integer) –
The size of the array property, for fixed-size arrays.

None means that the array property has variable size, and array_size attribute will also be None.
propagated (bool) –
If not None, specifies whether the property declaration has been propagated from a superclass, or the property value has been propagated from the creation class.

None means that propagation information is not available, and propagated attribute will also be None.
is_array (bool) –
A boolean indicating whether the property is an array (True) or a scalar (False).

If None, the is_array attribute will be inferred from the value parameter. If the value parameter is None, a scalar is assumed.
reference_class (string) –
For reference properties, the name of the class referenced by the property, or None indicating that the referenced class is unspecified.

For non-reference properties, must be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.

Note: Prior to pywbem 0.11, the corresponding attribute was inferred from the creation class name of a referenced instance. This was incorrect and has been fixed in pywbem 0.11.
qualifiers (qualifiers input object) – The qualifiers for the property declaration. Has no meaning for property values.
embedded_object (string) –
A string value indicating the kind of embedded object represented by the property value. Has no meaning for property declarations.

For details about the possible values, see the corresponding attribute.

None means that the value is unspecified, causing the same-named attribute in the CIMProperty object to be inferred. An exception is raised if it cannot be inferred.

False means the property value is not an embedded object, and is stored as None.

Examples:

# a string property:
CIMProperty("MyString", "abc")

# a uint8 property:
CIMProperty("MyNum", 42, "uint8")

# a uint8 property:
CIMProperty("MyNum", Uint8(42))

# a uint8 array property:
CIMProperty("MyNumArray", [1, 2, 3], "uint8")

# a reference property:
CIMProperty("MyRef", CIMInstanceName("Foo"))

# an embedded object property containing a class:
CIMProperty("MyEmbObj", CIMClass("Foo"))

# an embedded object property containing an instance:
CIMProperty("MyEmbObj", CIMInstance("Foo"),
            embedded_object="object")

# an embedded instance property:
CIMProperty("MyEmbInst", CIMInstance("Foo"))

# a string property that is Null:
CIMProperty("MyString", None, "string")

# a uint8 property that is Null:
CIMProperty("MyNum", None, "uint8")

# a reference property that is Null:
CIMProperty("MyRef", None, "reference", reference_class="MyClass")

# an embedded object property that is Null:
CIMProperty("MyEmbObj", None, "string", embedded_object="object")

# an embedded instance property that is Null:
CIMProperty("MyEmbInst", None, "string",
            embedded_object="instance")

Methods:

`__eq__`(other)	Equality test function for two `CIMProperty` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM property, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM property, for human consumption.
`copy`()	Return a new `CIMProperty` object that is a copy of this CIM property.
`tocimxml`()	Return the CIM-XML representation of this CIM property, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent])	Return the CIM-XML representation of this CIM property, as a unicode string.
`tomof`([is_instance, indent, maxline, line_pos])	Return a MOF string with the declaration of this CIM property for use in a CIM class, or the specification of this CIM property for use in a CIM instance.

Attributes:

`array_size`	The size of the fixed-size array of this CIM property.
`class_origin`	The class origin of this CIM property, identifying the most derived class that defines or overrides the property in the class hierarchy of the class owning the property.
`embedded_object`	A string value indicating the kind of embedded object represented by this CIM property value.
`is_array`	Boolean indicating that this CIM property is an array (as opposed to a scalar).
`name`	Name of this CIM property.
`propagated`	Boolean indicating that the property declaration has been propagated from a superclass, or that the property value has been propagated from the creation class.
`qualifiers`	Qualifiers (qualifier values) of this CIM property declaration.
`reference_class`	The name of the class referenced by this CIM reference property.
`type`	Name of the CIM data type of this CIM property.
`value`	Value of this CIM property.

__eq__(other)[source]

Equality test function for two CIMProperty objects.

The equality is based on their public attributes:

name
value
type
reference_class
embedded_object
is_array
array_size
propagated
class_origin
qualifiers

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMProperty object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]

Return a string representation of this CIM property, that is suitable for debugging.

The order of qualifiers will be preserved in the result.

__str__()[source]: Return a short string representation of this CIM property, for human consumption.

property array_size

The size of the fixed-size array of this CIM property.

None means that the array has variable size, or that the property is a scalar.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: integer

property class_origin

The class origin of this CIM property, identifying the most derived class that defines or overrides the property in the class hierarchy of the class owning the property.

None means that class origin information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

copy()[source]

Return a new CIMProperty object that is a copy of this CIM property.

This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:

The CIMQualifier objects in the qualifiers dictionary (but not the dictionary object itself)

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

property embedded_object

A string value indicating the kind of embedded object represented by this CIM property value.

Has no meaning for CIM property declarations.

The following values are defined for this parameter:

"instance": The property is declared with the EmbeddedInstance qualifier, indicating that the property value is an embedded instance of the class specified as the value of the EmbeddedInstance qualifier. The property value must be a CIMInstance object, or None.
"object": The property is declared with the EmbeddedObject qualifier, indicating that the property value is an embedded object (instance or class) of which the class name is not known. The property value must be a CIMInstance or CIMClass object, or None.
None, for properties not representing embedded objects.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property is_array

Boolean indicating that this CIM property is an array (as opposed to a scalar).

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property name

Name of this CIM property.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property propagated

Boolean indicating that the property declaration has been propagated from a superclass, or that the property value has been propagated from the creation class.

None means that propagation information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property qualifiers

Qualifiers (qualifier values) of this CIM property declaration.

Will not be None.

Each dictionary item specifies one qualifier value, with:

key (unicode string): Qualifier name. Its lexical case was preserved.
value (CIMQualifier): Qualifier value.

The order of qualifiers in the property is preserved.

This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of this class.

The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a CIMQualifier object:

prop = CIMProperty(...)
q1 = CIMQualifier('q1', ...) # may be CIM data type or CIMQualifier

prop.qualifiers['q1'] = q1  # Set "q1" to q1 (add if needed)
q1 = prop.qualifiers['q1']  # Access "q1"
del prop.qualifiers['q1']  # Delete "q1" from the class

Type: NocaseDict

property reference_class

The name of the class referenced by this CIM reference property.

Will be None for non-reference properties or if the referenced class is unspecified in reference properties.

Note that in CIM instances returned from a WBEM server, DSP0201 recommends this attribute not to be set. For CIM classes returned from a WBEM server, DSP0201 requires this attribute to be set.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

tocimxml()[source]

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

The returned CIM-XML representation is a PROPERTY, PROPERTY.REFERENCE, or PROPERTY.ARRAY element dependent on the property type, and consistent with DSP0201. Note that array properties cannot be of reference type.

The order of qualifiers in the returned CIM-XML representation is preserved from the CIMProperty object.

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

tocimxmlstr(indent=None)[source]

Return the CIM-XML representation of this CIM property, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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 object, as a unicode string.

tomof(is_instance=True, indent=0, maxline=80, line_pos=0)[source]

Return a MOF string with the declaration of this CIM property for use in a CIM class, or the specification of this CIM property for use in a CIM instance.

New in pywbem 0.9.

Even though pywbem supports qualifiers on CIMProperty objects that are used as property values within an instance, the returned MOF string for property values in instances does not contain any qualifier values.

The order of qualifiers is preserved.

Parameters

is_instance (bool) – If True, return MOF for a property value in a CIM instance. Else, return MOF for a property definition in a CIM class.
indent (integer) – Number of spaces to indent each line of the returned string, counted in the line with the property name.

Returns

MOF string.

Return type

property type

Name of the CIM data type of this CIM property.

Example: "uint8"

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property value

Value of this CIM property.

The property value is interpreted as an actual property value when this CIM property is used in a CIM instance, and as default value when this CIM property is used in a CIM class.

None means that the value is Null.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: CIM data type

CIMMethod

class pywbem.CIMMethod(name=None, return_type=None, parameters=None, class_origin=None, propagated=None, qualifiers=None)[source]

A method (declaration) in a CIM class.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

The init method stores the input parameters as-is and does not infer unspecified parameters from the others (like CIMProperty does).

Parameters

name (string) –
Name of this CIM method (just the method name, without class name or parenthesis).

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
return_type (string) –
Name of the CIM data type of the method return type (e.g. "uint32").

Must not be None or "reference".

ValueError is raised if the type is None, "reference", or not a valid CIM data type (see CIM data types).

Support for void return types: Pywbem also does not support void return types, consistent with the CIM architecture and MOF syntax (see DSP0004). Note that void return types could be represented in CIM-XML (see DSP0201).

Support for reference return types: Pywbem does not support reference return types of methods. The CIM architecture and MOF syntax support reference return types, and the CIM-XML protocol supports the invocation of methods with reference return types. However, CIM-XML does not support the representation of class declarations with methods that have reference return types.

Support for array return types: Pywbem does not support array return types of methods, consistent with the CIM architecture, MOF syntax and CIM-XML.
parameters (parameters input object) – Parameter declarations for the method.
class_origin (string) –
The CIM class origin of the method (the name of the most derived class that defines or overrides the method in the class hierarchy of the class owning the method).

None means that class origin information is not available, and the class_origin attribute will also be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
propagated (bool) –
If not None, specifies whether the method has been propagated from a superclass.

None means that propagation information is not available, and the the propagated attribute will also be None.
qualifiers (qualifiers input object) – The qualifiers for the method.

Methods:

`__eq__`(other)	Equality test function for two `CIMMethod` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM method, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM method, for human consumption.
`copy`()	Return a new `CIMMethod` object that is a copy of this CIM method.
`tocimxml`()	Return the CIM-XML representation of this CIM method, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent])	Return the CIM-XML representation of this CIM method, as a unicode string.
`tomof`([indent, maxline])	Return a MOF string with the declaration of this CIM method for use in a CIM class declaration.

Attributes:

`class_origin`	The class origin of this CIM method, identifying the most derived class that defines or overrides the method in the class hierarchy of the class owning the method.
`name`	Name of this CIM method.
`parameters`	Parameters of this CIM method.
`propagated`	Boolean indicating that this CIM method has been propagated from a superclass.
`qualifiers`	Qualifiers (qualifier values) of this CIM method.
`return_type`	Name of the CIM data type of the return type of this CIM method.

__eq__(other)[source]

Equality test function for two CIMMethod objects.

The equality is based on their public attributes:

name
qualifiers
parameters
return_type
class_origin
propagated

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMMethod object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]

Return a string representation of this CIM method, that is suitable for debugging.

The order of parameters and qualifiers will be preserved in the result.

__str__()[source]: Return a short string representation of this CIM method, for human consumption.

property class_origin

The class origin of this CIM method, identifying the most derived class that defines or overrides the method in the class hierarchy of the class owning the method.

None means that class origin information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

copy()[source]

Return a new CIMMethod object that is a copy of this CIM method.

This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:

The CIMParameter objects in the parameters dictionary (but not the dictionary object itself)
The CIMQualifier objects in the qualifiers dictionary (but not the dictionary object itself)

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

property name

Name of this CIM method.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property parameters

Parameters of this CIM method.

Will not be None.

Each dictionary item specifies one parameter, with:

key (unicode string): Parameter name. Its lexical case was preserved.
value (CIMParameter): Parameter declaration.

The order of parameters in the method is preserved.

This attribute is settable; setting it will cause the current parameters to be replaced with the new parameters. For details, see the description of the same-named init parameter of this class.

The parameters can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be a CIMParameter object:

meth = CIMMethod(...)
p1 = CIMParameter('p1', ...)  # must be a CIMParameter

meth.parameters['p1'] = p1  # Set "p1" to p1 (add if needed)
p1 = meth.parameters['p1']  # Access "p1"
del meth.parameters['p1']  # Delete "p1" from the class

Type: NocaseDict

property propagated

Boolean indicating that this CIM method has been propagated from a superclass.

None means that propagation information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property qualifiers

Qualifiers (qualifier values) of this CIM method.

Will not be None.

Each dictionary item specifies one qualifier value, with:

key (unicode string): Qualifier name. Its lexical case was preserved.
value (CIMQualifier): Qualifier value.

The order of qualifiers in the method is preserved.

This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of this class.

The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a CIMQualifier object:

meth = CIMMethod(...)
q1 = "..."  # may be CIM data type or CIMQualifier

meth.qualifiers['q1'] = q1  # Set "q1" to q1 (add if needed)
q1 = meth.qualifiers['q1']  # Access "q1"
del meth.qualifiers['q1']  # Delete "q1" from the class

Type: NocaseDict

property return_type

Name of the CIM data type of the return type of this CIM method.

Example: "uint32"

Will not be None or "reference".

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

tocimxml()[source]

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

The returned CIM-XML representation is a METHOD element consistent with DSP0201.

The order of parameters and qualifiers in the returned CIM-XML representation is preserved from the CIMMethod object.

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

tocimxmlstr(indent=None)[source]

Return the CIM-XML representation of this CIM method, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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 object, as a unicode string.

tomof(indent=0, maxline=80)[source]

Return a MOF string with the declaration of this CIM method for use in a CIM class declaration.

The order of parameters and qualifiers is preserved.

Parameters: indent (integer) – Number of spaces to indent each line of the returned string, counted in the line with the method name.
Returns: MOF string.
Return type: unicode string

CIMParameter

class pywbem.CIMParameter(name, type, reference_class=None, is_array=None, array_size=None, qualifiers=None, value=None, embedded_object=None)[source]

A CIM parameter (value or declaration).

This object can be used as parameter value in the InvokeMethod() operation, and as a parameter declaration in a CIMMethod object.

For parameter values in method invocations:

The value attribute is the actual value of the parameter.

Qualifiers are not allowed.

For parameter declarations in method declarations:

The value attribute is ignored.

Qualifiers are allowed.

Scalar (=non-array) parameters and items in array parameters may have a value of NULL (= None), any primitive CIM data type, reference type, or string type with embedded instance or embedded object.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

The init method stores the input parameters as-is and does not infer unspecified parameters from the others (like CIMProperty does).

Parameters

name (string) –
Name of this CIM parameter.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
type (string) –
Name of the CIM data type of this CIM parameter.

Example: "uint8"

Must not be None.

ValueError is raised if the type is None or not a valid CIM data type (see CIM data types).
reference_class (string) –
For reference parameters, the name of the class referenced by the parameter, or None indicating that the referenced class is unspecified.

For non-reference parameters, must be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
is_array (bool) –
A boolean indicating whether the parameter is an array (True) or a scalar (False).

If None, the is_array attribute will be inferred from the value parameter. If the value parameter is None, a scalar is assumed.
array_size (integer) –
The size of the array parameter, for fixed-size arrays.

None means that the array parameter has variable size, and the array_size attribute will also be None.
qualifiers (qualifiers input object) – The qualifiers for the parameter.
value –
The value of the CIM method parameter for the method invocation. Has no meaning for parameter declarations.

The specified value will be converted to a CIM data type using the rules documented in the description of cimvalue(), taking into account the type parameter.
embedded_object (string) –
A string value indicating the kind of embedded object represented by the parameter value (i.e. the value parameter). Has no meaning for parameter declarations.

For details about the possible values, see the corresponding attribute.

None means that the value is unspecified, causing the same-named attribute in the CIMParameter object to be inferred from the parameter value (i.e. the value parameter). An exception is raised if it cannot be inferred.

False means the parameter value is not an embedded object, and is stored as None.

Methods:

`__eq__`(other)	Equality test function for two `CIMParameter` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM parameter, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM parameter, for human consumption.
`copy`()	Return a new `CIMParameter` object that is a copy of this CIM parameter.
`tocimxml`([as_value])	Return the CIM-XML representation of this CIM parameter, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent, as_value])	Return the CIM-XML representation of this CIM parameter, as a unicode string.
`tomof`([indent, maxline])	Return a MOF string with the declaration of this CIM parameter for use in a CIM method declaration.

Attributes:

`array_size`	The size of the fixed-size array of this CIM parameter.
`embedded_object`	A string value indicating the kind of embedded object represented by this CIM parameter value.
`is_array`	Boolean indicating that this CIM parameter is an array (as opposed to a scalar).
`name`	Name of this CIM parameter.
`qualifiers`	Qualifiers (qualifier values) of this CIM parameter.
`reference_class`	The name of the class referenced by this CIM reference parameter.
`type`	Name of the CIM data type of this CIM parameter.
`value`	The value of this CIM parameter for the method invocation.

__eq__(other)[source]

Equality test function for two CIMParameter objects.

The equality is based on their public attributes:

name
type
reference_class
is_array
array_size
qualifiers
value
embedded_object

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMParameter object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]

Return a string representation of this CIM parameter, that is suitable for debugging.

The order of qualifiers will be preserved in the result.

__str__()[source]: Return a short string representation of this CIM parameter, for human consumption.

property array_size

The size of the fixed-size array of this CIM parameter.

None means that the array has variable size, or that the parameter is a scalar.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: integer

copy()[source]

Return a new CIMParameter object that is a copy of this CIM parameter.

This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:

The CIMQualifier objects in the qualifiers dictionary (but not the dictionary object itself)

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

property embedded_object

A string value indicating the kind of embedded object represented by this CIM parameter value.

Has no meaning for CIM parameter declarations.

The following values are defined for this parameter:

"instance": The parameter is declared with the EmbeddedInstance qualifier, indicating that the parameter value is an embedded instance of the class specified as the value of the EmbeddedInstance qualifier. The property value must be a CIMInstance object, or None.
"object": The parameter is declared with the EmbeddedObject qualifier, indicating that the parameter value is an embedded object (instance or class) of which the class name is not known. The parameter value must be a CIMInstance or CIMClass object, or None.
None, for parameters not representing embedded objects.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property is_array

Boolean indicating that this CIM parameter is an array (as opposed to a scalar).

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property name

Name of this CIM parameter.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property qualifiers

Qualifiers (qualifier values) of this CIM parameter.

Will not be None.

Each dictionary item specifies one qualifier value, with:

key (unicode string): Qualifier name. Its lexical case was preserved.
value (CIMQualifier): Qualifier value.

The order of qualifiers in the parameter is preserved.

This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of this class.

The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a CIMQualifier object:

parm = CIMParameter(...)
q1 = True  # may be CIM data type or CIMQualifier

parm.qualifiers['q1'] = q1  # Set "q1" to q1 (add if needed)
q1 = parm.qualifiers['q1']  # Access "q1"
del parm.qualifiers['q1']  # Delete "q1" from the class

Type: NocaseDict

property reference_class

The name of the class referenced by this CIM reference parameter.

Will be None for non-reference parameters or if the referenced class is unspecified in reference parameters.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

tocimxml(as_value=False)[source]

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

The returned CIM-XML representation can be created either as a parameter declaration for use in a method declaration, or as a parameter value for use in a method invocation.

If a parameter value is to be returned, the returned CIM-XML representation is a PARAMVALUE element with child elements dependent on the parameter type, and consistent with DSP0201.

If a parameter declaration is to be returned, the returned CIM-XML representation is a PARAMETER, PARAMETER.REFERENCE, PARAMETER.ARRAY, or PARAMETER.REFARRAY element dependent on the parameter type, and consistent with DSP0201.

The order of qualifiers in the returned CIM-XML representation of a parameter declaration is preserved from the CIMParameter object.

Parameters: as_value (bool) – If True, return the object as a parameter value. Otherwise, return the object as a parameter declaration.
Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.

tocimxmlstr(indent=None, as_value=False)[source]

Return the CIM-XML representation of this CIM parameter, as a unicode string.

New in pywbem 0.9.

The returned CIM-XML representation can be created either as a parameter declaration for use in a method declaration, or as a parameter value for use in a method invocation.

For the returned CIM-XML representation, see tocimxml().

Parameters

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.
as_value (bool) – If True, return the object as a parameter value. Otherwise, return the object as a parameter declaration.

Returns

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

tomof(indent=0, maxline=80)[source]

Return a MOF string with the declaration of this CIM parameter for use in a CIM method declaration.

The object is always interpreted as a parameter declaration; so the value and embedded_object attributes are ignored.

The order of qualifiers is preserved.

Parameters: indent (integer) – Number of spaces to indent each line of the returned string, counted in the line with the parameter name.
Returns: MOF string.
Return type: unicode string

property type

Name of the CIM data type of this CIM parameter.

Example: "uint8"

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property value

The value of this CIM parameter for the method invocation.

Has no meaning for parameter declarations.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

CIMQualifier

class pywbem.CIMQualifier(name, value, type=None, propagated=None, overridable=None, tosubclass=None, toinstance=None, translatable=None)[source]

A CIM qualifier value.

A qualifier represents metadata on a class, method, property, etc., and specifies information such as a documentation string or whether a property is a key.

CIMQualifier objects can be used to represent the qualifier values that are specified on a CIM element (e.g. on a CIM class). In that case, the propagated property is always False, and the effective values of applicable but unspecified qualifiers need to be determined by users, by considering the default value of the corresponding qualifier type, the propagation and override flavors of the qualifier, and the qualifier values that have been specified in the class ancestry of the CIM element in question.

CIMQualifier objects can also be used to represent the effective values of all applicable qualifiers on a CIM element, including those that have not been specified, e.g. in the MOF declaration of the CIM element. In this case, the CIMQualifier objects for qualifier values that are specified in MOF represent the specified values, and their propagated property is False. The CIMQualifier objects for qualifier values that are not specified in MOF represent the effective values, and their propagated property is True.

Whether a set of CIMQualifier objects on a CIM object represents just the specified qualifiers or all applicable qualifiers needs to be known from the context.

CIMQualifier has properties that represent qualifier flavors (tosubclass, toinstance, overridable, and translatable). If any of these flavor properties is not None, the qualifier value represented by the CIMQualifier object implicitly defines a qualifier type. Implicitly defined qualifier types have been deprecated in DSP0004. The implicitly defined qualifier type is conceptual and is not materialized as a CIMQualifierDeclaration object.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

The init method infers optional parameters that are not specified (for example, it infers type from the Python type of value and other information). If the specified parameters are inconsistent, an exception is raised. If an optional parameter is needed for some reason, an exception is raised.

Parameters

name (string) –
Name of the qualifier.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or other suitable types) –
Value of the qualifier.

None means that the qualifier is Null, and the same-named attribute in the CIMQualifier object will also be None.

The specified value will be converted to a CIM data type using the rules documented in the description of cimvalue(), taking into account the type parameter.
type (string) –
Name of the CIM data type of the qualifier (e.g. "uint8").

None will cause the type to be inferred from the value parameter, raising ValueError if it cannot be inferred (for example when value is None or a Python integer).

ValueError is raised if the type is not a valid CIM data type (see CIM data types).
propagated (bool) –
If not None, specifies whether the qualifier value has been propagated from a superclass.

None means that this information is not available, and the propagated attribute will also be None.
overridable (bool) –
If not None, specifies whether the qualifier value is overridable in subclasses.

None means that this information is not available, and the overridable attribute will also be None.
tosubclass (bool) –
If not None, specifies whether the qualifier value propagates to subclasses.

None means that this information is not available, and the tosubclass attribute will also be None.
toinstance (bool) –
If not None, specifies whether the qualifier value propagates to instances.

None means that this information is not available, and the toinstance attribute will also be None.

Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
translatable (bool) –
If not None, specifies whether the qualifier is translatable.

None means that this information is not available, and the translatable attribute will also be None.

Examples:

# a string qualifier:
CIMQualifier("MyString", "abc")

# a uint8 qualifier:
CIMQualifier("MyNum", 42, "uint8")

# a uint8 qualifier:
CIMQualifier("MyNum", Uint8(42))

# a uint8 array qualifier:
CIMQualifier("MyNumArray", [1, 2, 3], "uint8")

# a string qualifier that is Null:
CIMQualifier("MyString", None, "string")

# a uint8 qualifier that is Null:
CIMQualifier("MyNum", None, "uint8")

Methods:

`__eq__`(other)	Equality test function for two `CIMQualifier` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM qualifier, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM qualifier, for human consumption.
`copy`()	Return a new `CIMQualifier` object that is a copy of this CIM qualifier.
`tocimxml`()	Return the CIM-XML representation of this CIM qualifier, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent])	Return the CIM-XML representation of this CIM qualifier, as a unicode string.
`tomof`([indent, maxline, line_pos])	Return a MOF string with the specification of this CIM qualifier as a qualifier value.

Attributes:

`name`	Name of this CIM qualifier.
`overridable`	If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
`propagated`	Boolean indicating that the qualifier value has been propagated from a superclass.
`toinstance`	If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
`tosubclass`	If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
`translatable`	If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
`type`	Name of the CIM data type of this CIM qualifier.
`value`	Value of this CIM qualifier.

__eq__(other)[source]

Equality test function for two CIMQualifier objects.

The equality is based on their public attributes:

name
type
value
propagated
overridable
tosubclass
toinstance
translatable

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMQualifier object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]: Return a string representation of this CIM qualifier, that is suitable for debugging.

__str__()[source]: Return a short string representation of this CIM qualifier, for human consumption.

copy()[source]

Return a new CIMQualifier object that is a copy of this CIM qualifier.

Objects of this class have no mutable types in any attributes, so modifications of the original object will not affect the returned copy, and vice versa.

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

property name

Name of this CIM qualifier.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property overridable

If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.

If True, specifies the EnableOverride flavor(the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor(the qualifier value is not overridable in subclasses).

None means that this information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property propagated

Boolean indicating that the qualifier value has been propagated from a superclass.

None means that propagation information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

tocimxml()[source]

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

The returned CIM-XML representation is a QUALIFIER element consistent with DSP0201.

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

tocimxmlstr(indent=None)[source]

Return the CIM-XML representation of this CIM qualifier, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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 object, as a unicode string.

property toinstance

If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.

If True specifies the ToInstance flavor(the qualifier value propagates to instances. If False, specifies that qualifier values do not propagate to instances. There is no flavor corresponding to toinstance=False.

None means that this information is not available.

Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

tomof(indent=3, maxline=80, line_pos=0)[source]

Return a MOF string with the specification of this CIM qualifier as a qualifier value.

The items of array values are tried to keep on the same line. If the generated line would exceed the maximum MOF line length, the value is split into multiple lines, on array item boundaries, and/or within long strings on word boundaries.

If a string value (of a scalar value, or of an array item) is split into multiple lines, the first line of the value is put onto a line on its own.

Parameters: indent (integer) – For a multi-line result, the number of spaces to indent each line except the first line (on which the qualifier name appears). For a single-line result, ignored.
Returns: MOF string.
Return type: unicode string

property tosubclass

If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.

If True, specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier values does not propagate to subclasses).

None means that this information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property translatable

If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.

If True, specifies the Translatable flavor (the qualifier is translatable); if False specifies that the qualfier is not translatable. There is no flavor corresponding to translatable=False.

None means that this information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property type

Name of the CIM data type of this CIM qualifier.

Example: "uint8"

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property value

Value of this CIM qualifier.

None means that the value is Null.

For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: CIM data type

CIMQualifierDeclaration

class pywbem.CIMQualifierDeclaration(name, type, value=None, is_array=False, array_size=None, scopes=None, overridable=None, tosubclass=None, toinstance=None, translatable=None)[source]

A CIM qualifier type is the declaration of a qualifier and defines the attributes of qualifier name, qualifier type, value, scopes, and flavors for the qualifier.

The scope of a qualifer determines the kinds of schema elements on which it can be specified.

Value specifies the default value for the qualifier.

Flavors specify certain characteristics of the qualifier such as its value propagation from the ancestry of the qualified element and its translatability.

Flavors attributes must be specifically set on construction of the CIMQualifierDeclaration or they will be set to None. This differs from the DMTF specification DSP0004 where default values are defined as follows:

Has the EnableOverride flavor; overridable = True

Has the ToSubClass flavor; tosubclass = True

Does not have theTranslatable flavor; translatable = False

Does not have ToInstance flavor; toinstance = False. Not defined in DSP0004 and deprecated in the DMTF protocol specification DSP0200

Because None is allowed as a value for the flavors attributes in constructing a CIMQualifierDeclaration, the user must insure that any flavor which has the value None is set to its default value if required for subsequent processing.

The pywbem MOF compiler supplies all of the flavor values so that those which were not specified in the MOF are set to the DMTF defined default values.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.

Parameters

name (string) –
Name of the qualifier.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
type (string) –
Name of the CIM data type of the qualifier (e.g. "uint8").

Must not be None.

ValueError is raised if the type is None or not a valid CIM data type (see CIM data types).
value (CIM data type or other suitable types) –
Default value of the qualifier.

None means a default value of Null, and the value attribute will also be None.

The specified value will be converted to a CIM data type using the rules documented in the description of cimvalue(), taking into account the type parameter.
is_array (bool) –
A boolean indicating whether the qualifier is an array (True) or a scalar (False).

If None, the is_array attribute will be inferred from the value parameter. If the value parameter is None, a scalar is assumed.
array_size (integer) –
The size of the array qualifier, for fixed-size arrays.

None means that the array qualifier has variable size, and the array_size attribute will also be None.
scopes (dict or NocaseDict) –
Scopes of the qualifier.

A shallow copy of the provided dictionary will be stored in the CIMQualifierDeclaration object.

Each dictionary item specifies one scope value, with:
- key (string): Scope name, in upper case.
  
  Must not be None.
- value (bool): Scope value, specifying whether the qualifier has that scope (i.e. can be applied to a CIM element of that kind).
Valid scope names are “CLASS”, “ASSOCIATION”, “REFERENCE”, “PROPERTY”, “METHOD”, “PARAMETER”, “INDICATION”, and “ANY”.

None is interpreted as an empty set of scopes.

For details about the dictionary items, see the corresponding attribute.
overridable (bool) –
If not None, defines the flavor that defines whether the qualifier value is overridable in subclasses.

None means that this information is not available, and the overridable attribute will also be None.
tosubclass (bool) –
If not None, specifies the flavor that defines whether the qualifier value propagates to subclasses.

None means that this information is not available, and the tosubclass attribute will also be None.
toinstance (bool) –
If not None, specifies the flavor that defines whether the qualifier value propagates to instances.

None means that this information is not available, and the toinstance attribute will also be None.

Note that DSP0200 has deprecated the presence of qualifier values on CIM instances and this flavor is not defined in DSP0004
translatable (bool) –
If not None, specifies the flavor that defines whether the qualifier is translatable.

None means that this information is not available, and the translatable attribute will also be None.

Methods:

`__eq__`(other)	Equality test function for two `CIMQualifierDeclaration` objects.
`__hash__`()	Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes.
`__ne__`(other)	Non-equality test for two CIM objects.
`__repr__`()	Return a string representation of this CIM qualifier type, that is suitable for debugging.
`__str__`()	Return a short string representation of this CIM qualifier type, for human consumption.
`copy`()	Return a new `CIMQualifierDeclaration` object that is a copy of this CIM qualifier type.
`tocimxml`()	Return the CIM-XML representation of this CIM qualifier type, as an object of an appropriate subclass of Element.
`tocimxmlstr`([indent])	Return the CIM-XML representation of this CIM qualifier type, as a unicode string.
`tomof`([maxline])	Return a MOF string with the declaration of this CIM qualifier type.

Attributes:

`array_size`	The size of the fixed-size array of this CIM qualifier type.
`is_array`	Boolean indicating that this CIM qualifier type is an array (as opposed to a scalar).
`name`	Name of this CIM qualifier type.
`overridable`	If True, specifies the EnableOverride flavor (the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor (the qualifier value is not overridable in subclasses).
`scopes`	Scopes of this CIM qualifier type.
`toinstance`	If True, specifies the ToInstance flavor.
`tosubclass`	If True specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier value does not propagate to subclasses).
`translatable`	If True, specifies the Translatable flavor.
`type`	Name of the CIM data type of this CIM qualifier type.
`value`	Default value of this CIM qualifier type.

__eq__(other)[source]

Equality test function for two CIMQualifierDeclaration objects.

The equality is based on their public attributes:

name
type
value
is_array
array_size
scopes
overridable
tosubclass
toinstance
translatable

The equality test takes into account any case insensitivities described for these attributes.

Raises TypeError, if the other object is not a CIMQualifierDeclaration object.

__hash__()[source]: Return a hash value based on the public attributes of this class, taking into account any case insensitivities described for these attributes. This approach causes this class to be unchanged-hashable.

__repr__()[source]

Return a string representation of this CIM qualifier type, that is suitable for debugging.

The scopes will be ordered by their names in the result.

__str__()[source]: Return a short string representation of this CIM qualifier type, for human consumption.

property array_size

The size of the fixed-size array of this CIM qualifier type.

None means that the array has variable size (or that the qualifier type is not an array).

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: integer

copy()[source]

Return a new CIMQualifierDeclaration object that is a copy of this CIM qualifier type.

Objects of this class have no mutable types in any attributes, so modifications of the original object will not affect the returned copy, and vice versa.

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

property is_array

Boolean indicating that this CIM qualifier type is an array (as opposed to a scalar).

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property name

Name of this CIM qualifier type.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property overridable

If True, specifies the EnableOverride flavor (the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor (the qualifier value is not overridable in subclasses).

None means that this information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property scopes

Scopes of this CIM qualifier type.

Each dictionary item specifies one scope value, with:

key (unicode string): Scope name, in upper case.
value (bool): Scope value, specifying whether the qualifier has that scope (i.e. can be applied to a CIM element of that kind).

Valid scope names are “CLASS”, “ASSOCIATION”, “INDICATION”, “PROPERTY”, “REFERENCE”, “METHOD”, “PARAMETER”, and “ANY”.

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: NocaseDict

tocimxml()[source]

Return the CIM-XML representation of this CIM qualifier type, as an object of an appropriate subclass of Element.

The returned CIM-XML representation is a QUALIFIER.DECLARATION element consistent with DSP0201.

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

tocimxmlstr(indent=None)[source]

Return the CIM-XML representation of this CIM qualifier type, as a unicode string.

New in pywbem 0.9.

For the returned CIM-XML representation, see tocimxml().

Parameters

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 object, as a unicode string.

property toinstance

If True, specifies the ToInstance flavor. This flavor specifies that the qualifier value propagates to instances. If False, specifies that qualifier values do not propagate to instances. There is no flavor corresponding to toinstance=False.

None means that this information is not available.

Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

tomof(maxline=80)[source]

Return a MOF string with the declaration of this CIM qualifier type.

The returned MOF string conforms to the qualifierDeclaration ABNF rule defined in DSP0004.

Qualifier flavors are included in the returned MOF string only when the information is available (i.e. the value of the corresponding attribute is not None).

Because DSP0004 does not support instance qualifiers, and thus does not define a flavor keyword for the toinstance attribute, that flavor is not included in the returned MOF string.

Returns: MOF string.
Return type: unicode string

property tosubclass

If True specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier value does not propagate to subclasses).

None means that this information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property translatable

If True, specifies the Translatable flavor. This flavor specifies that the qualifier is translatable. If False, specifies that the qualfier is not translatable. There is no flavor corresponding to translatable=False.

None means that this information is not available.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: bool

property type

Name of the CIM data type of this CIM qualifier type.

Example: "uint8".

Will not be None.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: unicode string

property value

Default value of this CIM qualifier type.

None means that the value is Null.

For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Type: CIM data type

CIM data types

Python classes for representing values of CIM data types, and related conversion functions.

The following table shows how CIM data types are represented in Python. Note that some basic CIM data types are represented with built-in Python types.

CIM data type	Python type
boolean	`bool`
char16	string or `Char16`
string	string
string (EmbeddedInstance)	`CIMInstance`
string (EmbeddedObject)	`CIMInstance` or `CIMClass`
datetime	`CIMDateTime`
reference	`CIMInstanceName`
uint8	`Uint8`
uint16	`Uint16`
uint32	`Uint32`
uint64	`Uint64`
sint8	`Sint8`
sint16	`Sint16`
sint32	`Sint32`
sint64	`Sint64`
real32	`Real32`
real64	`Real64`
[] (array)	`list`

The CIM NULL value is represented with Python None which can be used for any CIM typed value to represent NULL.

Note that init methods of pywbem classes that take CIM typed values as input may support Python types in addition to those shown above. For example, the CIMProperty class represents property values of CIM datetime type internally as CIMDateTime objects, but its init method accepts datetime.timedelta objects, datetime.datetime objects, string, in addition to CIMDateTime objects.

class pywbem.CIMType[source]

Base type for all CIM data types defined in this package.

Attributes:

The name of the CIM datatype, as a string.

cimtype = None: The name of the CIM datatype, as a string. See CIM data types for details.

class pywbem.CIMDateTime(dtarg)[source]

A value of CIM data type datetime.

The object represents either a timezone-aware point in time, or a time interval.

Two objects of this class compare equal if their public attributes compare equal. Objects of this class are immutable and hashable, with the hash value being based on their public attributes.

Parameters

dtarg –

The value from which the object is initialized, as one of the following types:

A string object will be interpreted as CIM datetime format (see DSP0004) and will result in a point in time or a time interval. The use of asterisk characters in the value is supported according to the rules defined in DSP0004 (e.g. “20180911124613.128***:000”).
A datetime.datetime object will result in a point in time. If the datetime.datetime object is timezone-aware (see MinutesFromUTC), the specified timezone will be used. Otherwise, a default timezone of UTC will be assumed.
A datetime.timedelta object will result in a time interval.
Another CIMDateTime object will be copied.

Methods:

`__eq__`(other)	Equality test function for two `CIMDateTime` objects.
`__hash__`()	Return a hash value based on the public attributes of this class.
`fromtimestamp`(ts[, tzi])	Factory method that returns a new `CIMDateTime` object from a POSIX timestamp value and optional timezone information.
`get_local_utcoffset`()	Return the timezone offset of the current local timezone as +/- minutes from UTC.
`now`([tzi])	Factory method that returns a new `CIMDateTime` object representing the current date and time.

Attributes:

`cimtype`	The name of the CIM datatype `"datetime"`
`datetime`	The point in time represented by this object, as a `datetime.datetime` object.
`is_interval`	A boolean indicating whether this object represents a time interval (True) or a point in time (False).
`minutes_from_utc`	The timezone offset of this point in time object as +/- minutes from UTC.
`precision`	Precision of the time interval or point in time represented by this object, if the datetime input string contained asterisk characters.
`timedelta`	The time interval represented by this object, as a `datetime.timedelta` object.

__eq__(other)[source]

Equality test function for two CIMDateTime objects.

The equality is based on their public attributes.

Note that a CIMDateTime object represents either a time interval or a point in time but never both. Therefore, an object representing an interval is never equal to an object representing a point in time.

Returns False if the other object is not a CIMDateTime object.

__hash__()[source]: Return a hash value based on the public attributes of this class. Because these attributes are not modifiable, objects of this class are hashable (and not just unchanged-hashable).

__repr__()[source]: Return a string representation suitable for debugging.

__str__()[source]: Return a string representing the object in CIM datetime format.

cimtype = 'datetime': The name of the CIM datatype "datetime"

property datetime

The point in time represented by this object, as a datetime.datetime object.

None if this object represents a time interval.

classmethod fromtimestamp(ts, tzi=None)[source]

Factory method that returns a new CIMDateTime object from a POSIX timestamp value and optional timezone information.

A POSIX timestamp value is the number of seconds since “the epoch”, i.e. 1970-01-01 00:00:00 UTC. Thus, a POSIX timestamp value is unambiguous w.r.t. the timezone, but it is not timezone-aware.

The optional timezone information is used to convert the CIM datetime value into the desired timezone. That does not change the point in time that is represented by the value, but it changes the value of the hhmmss components of the CIM datetime value to compensate for changes in the timezone offset component.

Parameters

ts (integer) – POSIX timestamp value.
tzi (MinutesFromUTC) – Timezone information. None means that the current local timezone is used.

Returns

A new CIMDateTime object representing the specified point in time.

static get_local_utcoffset()[source]

Return the timezone offset of the current local timezone as +/- minutes from UTC.

A positive value indicates minutes east of UTC, and a negative value indicates minutes west of UTC.

property is_interval: A boolean indicating whether this object represents a time interval (True) or a point in time (False).

property minutes_from_utc

The timezone offset of this point in time object as +/- minutes from UTC.

A positive value of the timezone offset indicates minutes east of UTC, and a negative value indicates minutes west of UTC.

0, if this object represents a time interval.

classmethod now(tzi=None)[source]

Factory method that returns a new CIMDateTime object representing the current date and time.

The optional timezone information is used to convert the CIM datetime value into the desired timezone. That does not change the point in time that is represented by the value, but it changes the value of the hhmmss components of the CIM datetime value to compensate for changes in the timezone offset component.

Parameters: tzi (MinutesFromUTC) – Timezone information. None means that the current local timezone is used.
Returns: A new CIMDateTime object representing the current date and time.

property precision

Precision of the time interval or point in time represented by this object, if the datetime input string contained asterisk characters.

The precision is the 0-based index of the first asterisk character in the datetime input string, or None if there were no asterisk characters. For example, the precision of the timestamp value “201809121230**.******+000” is 12.

property timedelta

The time interval represented by this object, as a datetime.timedelta object.

None if this object represents a point in time.

class pywbem.MinutesFromUTC(offset)[source]

Timezone information (an implementation of datetime.tzinfo) that represents a fixed offset in +/- minutes from UTC and is thus suitable for the CIM datetime data type.

Objects of this class are needed in order to make datetime.datetime objects timezone-aware, in order to be useable as input data to the timezone-aware CIMDateTime type.

They are also used to provide timezone information to now() and fromtimestamp()

Example:

from datetime import datetime
from time import time
import pywbem

# Create a timezone-aware datetime object (for CEDT = UTC+2h), and
# convert that to CIM datetime:

dt = datetime(year=2016, month=3, day=31, hour=19, minute=30,
              second=40, microsecond=654321,
              tzinfo=pywbem.MinutesFromUTC(120))
cim_dt = pywbem.CIMDateTime(dt)

# Convert a POSIX timestamp value to CIM datetime (for EST = UTC-5h):

posix_ts = time()  # seconds since the epoch, not timezone-aware
cim_dt = pywbem.CIMDateTime.fromtimestamp(posix_ts,
                                          pywbem.MinutesFromUTC(-300))

Parameters

offset (integer) –

Timezone offset to be represented in the CIM datetime value in +/- minutes from UTC.

This is the offset of local time to UTC (including DST offset), where a positive value indicates minutes east of UTC, and a negative value indicates minutes west of UTC.

Methods:

`dst`(dt)	An implementation of the corresponding base class method, (see `datetime.tzinfo.dst()` for its description), which needs to return the offset caused by DST, as a `datetime.timedelta` object.
`tzname`(dt)	An implementation of the corresponding base class method, (see `datetime.tzinfo.tzname()` for its description), which needs to return the name of the timezone of the specified datetime object.
`utcoffset`(dt)	An implementation of the corresponding base class method (see `datetime.tzinfo.utcoffset()` for its description), which needs to return the offset of local time to UTC (including DST offset), as a `datetime.timedelta` object.

__repr__()[source]: Return a string representation suitable for debugging.

dst(dt)[source]

An implementation of the corresponding base class method, (see datetime.tzinfo.dst() for its description), which needs to return the offset caused by DST, as a datetime.timedelta object. This method is called by the Python datetime classes, and a pywbem user normally does not have to deal with it.

This implementation returns an offset of 0 (indicating that DST is not in effect), for any specified dt parameter, because CIM datetime values do not represent DST information.

tzname(dt)[source]

An implementation of the corresponding base class method, (see datetime.tzinfo.tzname() for its description), which needs to return the name of the timezone of the specified datetime object.

This implementation returns the timezone offset formatted as a signed HH:MM string, where positive values are east of UTC.

utcoffset(dt)[source]

An implementation of the corresponding base class method (see datetime.tzinfo.utcoffset() for its description), which needs to return the offset of local time to UTC (including DST offset), as a datetime.timedelta object. This method is called by the Python datetime classes, and a pywbem user normally does not have to deal with it.

This implementation returns the offset used to initialize the object, for any specified dt parameter.

class pywbem.Char16(content='')[source]

A value of CIM data type char16.

This class is derived from unicode string.

Normally, values of CIM data type char16 are represented using unicode string objects. This class can be used to represent values of CIM data type char16 when it matters to distinguish them from values of CIM data type string. The only situation where that matters is for keybindings, because that allows properly setting the TYPE attribute on KEYVALUE elements when creating the CIM-XML representation for a keybinding.

Attributes:

The name of the CIM datatype "char16"

cimtype = 'char16': The name of the CIM datatype "char16"

class pywbem.CIMInt(*args, **kwargs)[source]

Base type for CIM integer data types. Derived from CIMType and int (for Python 3) or long (for Python 2).

This class has a concept of a valid range for the represented integer, based upon the capability of the CIM data type as defined in DSP0004. The additional constraints defined by possible MinValue or MaxValue qualifiers are not taken into account at this level.

The valid value range is enforced when an instance of a subclass of this class (e.g. Uint8) is created. Values outside of the valid range raise a ValueError. The enforcement of the valid value range can be disabled via the configuration variable ENFORCE_INTEGER_RANGE.

Two objects of subclasses of this base class compare equal if their numeric values compare equal. Objects of this class are immutable and hashable, with the hash value being based on its numeric value.

Instances of subclasses of this class can be initialized with the usual input arguments supported by integer, for example:

>>> pywbem.Uint8(42)
Uint8(cimtype='uint8', 42)

>>> pywbem.Uint8('42')
Uint8(cimtype='uint8', 42)

>>> pywbem.Uint8('2A', 16)
Uint8(cimtype='uint8', 42)

>>> pywbem.Uint8('100', 16)
Traceback (most recent call last):
  . . .
ValueError: Integer value 256 is out of range for CIM datatype uint8

>>> pywbem.Uint8(100, 10)
Traceback (most recent call last):
  . . .
TypeError: int() can't convert non-string with explicit base

Attributes:

`maxvalue`	The maximum valid value for the integer, according to the capabilities of its CIM data type.
`minvalue`	The minimum valid value for the integer, according to the capabilities of its CIM data type.

__repr__()[source]: Return a string representation suitable for debugging.

maxvalue = None: The maximum valid value for the integer, according to the capabilities of its CIM data type. See CIM data types for a list of CIM integer data types.

minvalue = None: The minimum valid value for the integer, according to the capabilities of its CIM data type. See CIM data types for a list of CIM integer data types.

class pywbem.Uint8(*args, **kwargs)[source]

A value of CIM data type uint8. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'uint8': The name of the CIM datatype

maxvalue = 255: The maximum valid value for the CIM datatype

minvalue = 0: The minimum valid value for the CIM datatype

class pywbem.Sint8(*args, **kwargs)[source]

A value of CIM data type sint8. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'sint8': The name of the CIM datatype

maxvalue = 127: The maximum valid value for the CIM datatype

minvalue = -128: The minimum valid value for the CIM datatype

class pywbem.Uint16(*args, **kwargs)[source]

A value of CIM data type uint16. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'uint16': The name of the CIM datatype

maxvalue = 65535: The maximum valid value for the CIM datatype

minvalue = 0: The minimum valid value for the CIM datatype

class pywbem.Sint16(*args, **kwargs)[source]

A value of CIM data type sint16. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'sint16': The name of the CIM datatype

maxvalue = 32767: The maximum valid value for the CIM datatype

minvalue = -32768: The minimum valid value for the CIM datatype

class pywbem.Uint32(*args, **kwargs)[source]

A value of CIM data type uint32. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'uint32': The name of the CIM datatype

maxvalue = 4294967295: The maximum valid value for the CIM datatype

minvalue = 0: The minimum valid value for the CIM datatype

class pywbem.Sint32(*args, **kwargs)[source]

A value of CIM data type sint32. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'sint32': The name of the CIM datatype

maxvalue = 2147483647: The maximum valid value for the CIM datatype

minvalue = -2147483648: The minimum valid value for the CIM datatype

class pywbem.Uint64(*args, **kwargs)[source]

A value of CIM data type uint64. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'uint64': The name of the CIM datatype

maxvalue = 18446744073709551615: The maximum valid value for the CIM datatype

minvalue = 0: The minimum valid value for the CIM datatype

class pywbem.Sint64(*args, **kwargs)[source]

A value of CIM data type sint64. Derived from CIMInt.

For details on CIM integer data types, see CIMInt.

Attributes:

`cimtype`	The name of the CIM datatype
`maxvalue`	The maximum valid value for the CIM datatype
`minvalue`	The minimum valid value for the CIM datatype

cimtype = 'sint64': The name of the CIM datatype

maxvalue = 9223372036854775807: The maximum valid value for the CIM datatype

minvalue = -9223372036854775808: The minimum valid value for the CIM datatype

class pywbem.CIMFloat(x=0, /)[source]

Base type for real (floating point) CIM data types.

Two objects of subclasses of this base class compare equal if their numeric values compare equal. Objects of this class are immutable and hashable, with the hash value being based on its numeric value.

Note that equality comparison of floating point numbers in Python (and in almost any programming language) comes with some surprises. See “Floating Point Arithmetic: Issues and Limitations” for details, and specifically “Comparing Floating Point Numbers, 2012 Edition” on the topic of equality comparison. The same issues apply to hash values that are based on the numeric value of floating point numbers. Therefore, it is not recommended to perform equality comparison of objects of subclasses of this class, or to use them as dictionary keys or as members in sets.

__repr__()[source]: Return a string representation suitable for debugging.

class pywbem.Real32(x=0, /)[source]

A value of CIM data type real32. Derived from CIMFloat.

It is not recommended to perform equality comparison on objects of this class, or to use them as dictionary keys or as members in sets. See CIMFloat for details.

Attributes:

The name of the CIM datatype

cimtype = 'real32': The name of the CIM datatype

class pywbem.Real64(x=0, /)[source]

A value of CIM data type real64. Derived from CIMFloat.

It is not recommended to perform equality comparison on objects of this class, or to use them as dictionary keys or as members in sets. See CIMFloat for details.

Attributes:

The name of the CIM datatype

cimtype = 'real64': The name of the CIM datatype

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':
  - 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'):
  - 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':
  - 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

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.

CIM status codes

This section defines constants for two areas:

CIM status codes (the CIM_ERR_* symbols). They are for example stored in CIMError exceptions.
Other constants.

Note: For tooling reasons, the constants are shown in the namespace pywbem._cim_constants. However, they are also available in the pywbem namespace and should be used from there.

pywbem._cim_constants.CIM_ERR_ACCESS_DENIED = 2: Access to a CIM resource is not available to the client.

pywbem._cim_constants.CIM_ERR_ALREADY_EXISTS = 11: The operation cannot be invoked because an object already exists.

pywbem._cim_constants.CIM_ERR_CLASS_HAS_CHILDREN = 8: The operation cannot be invoked on this class because it has subclasses.

pywbem._cim_constants.CIM_ERR_CLASS_HAS_INSTANCES = 9: The operation cannot be invoked on this class because one or more instances of this class exist.

pywbem._cim_constants.CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED = 26: The WBEM server does not support continuation on error. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_FAILED = 1: A general error occurred that is not covered by a more specific error code.

pywbem._cim_constants.CIM_ERR_FILTERED_ENUMERATION_NOT_SUPPORTED = 25: Using a a filter query in pulled enumerations is not supported by the WBEM server. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_INVALID_CLASS = 5: The specified class does not exist.

pywbem._cim_constants.CIM_ERR_INVALID_ENUMERATION_CONTEXT = 21: The enumeration identified by the specified context cannot be found, is in a closed state, does not exist, or is otherwise invalid. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_INVALID_NAMESPACE = 3: The target namespace does not exist.

pywbem._cim_constants.CIM_ERR_INVALID_OPERATION_TIMEOUT = 22: The specified operation timeout is not supported by the WBEM server. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_INVALID_PARAMETER = 4: One or more parameter values passed to the method are not valid.

pywbem._cim_constants.CIM_ERR_INVALID_QUERY = 15: The query is not valid for the specified query language.

pywbem._cim_constants.CIM_ERR_INVALID_SUPERCLASS = 10: The operation cannot be invoked because the specified superclass does not exist.

pywbem._cim_constants.CIM_ERR_METHOD_NOT_AVAILABLE = 16: The extrinsic method cannot be invoked.

pywbem._cim_constants.CIM_ERR_METHOD_NOT_FOUND = 17: The specified extrinsic method does not exist.

pywbem._cim_constants.CIM_ERR_NAMESPACE_NOT_EMPTY = 20: The specified namespace is not empty. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_NOT_FOUND = 6: The requested object cannot be found. The operation can be unsupported on behalf of the WBEM server in general or on behalf of an implementation of a management profile.

pywbem._cim_constants.CIM_ERR_NOT_SUPPORTED = 7: The requested operation is not supported on behalf of the WBEM server, or on behalf of a provided class. If the operation is supported for a provided class but is not supported for particular instances of that class, then CIM_ERR_FAILED shall be used.

pywbem._cim_constants.CIM_ERR_NO_SUCH_PROPERTY = 12: The specified property does not exist.

pywbem._cim_constants.CIM_ERR_PULL_CANNOT_BE_ABANDONED = 24: The attempt to abandon a concurrent pull operation on the same enumeration failed. The concurrent pull operation proceeds normally. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_PULL_HAS_BEEN_ABANDONED = 23: The pull operation has been abandoned due to execution of a concurrent CloseEnumeration operation on the same enumeration. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED = 14: The query language is not recognized or supported.

pywbem._cim_constants.CIM_ERR_SERVER_IS_SHUTTING_DOWN = 28: The WBEM server is shutting down and cannot process the operation. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_SERVER_LIMITS_EXCEEDED = 27: The WBEM server has failed the operation based upon exceeding server limits. New in pywbem 0.9.

pywbem._cim_constants.CIM_ERR_TYPE_MISMATCH = 13: The value supplied is not compatible with the type.

pywbem._cim_constants.DEFAULT_NAMESPACE = 'root/cimv2': Default CIM namespace for WBEM connection

pywbem._cim_constants.DEFAULT_URL_PORT_HTTP = 5988: Default port number for http WBEM connection New in pywbem 1.0.

pywbem._cim_constants.DEFAULT_URL_PORT_HTTPS = 5989: Default port number for https WBEM connection New in pywbem 1.0.

pywbem._cim_constants.DEFAULT_URL_SCHEME = 'http': Default URL scheme for WBEM connection New in pywbem 1.0.

Exceptions

The following exceptions are pywbem specific exceptions that can be raised at the WBEM client library API.

class pywbem.ConnectionError(message, conn_id=None)[source]

This exception indicates a problem with the connection to the WBEM server. A retry may or may not succeed.

Derived from Error.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.

Variables

args – A tuple (message, ) set from the corresponding init arguments.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.AuthError(message, conn_id=None)[source]

This exception indicates an authentication error with the WBEM server, either during TLS/SSL handshake, or during HTTP-level authentication.

Derived from Error.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.

Variables

args – A tuple (message, ) set from the corresponding init arguments.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.HTTPError(status, reason, cimerror=None, cimdetails=None, conn_id=None, request_data=None, response_data=None)[source]

This exception indicates that the WBEM server returned an HTTP response with a bad HTTP status code.

Derived from Error.

The args instance variable is a tuple (status, reason, cimerror, cimdetails).

The message instance variable is not set.

Occurrence of this exception nearly always indicates an issue with the WBEM server.

Parameters

status (integer) – HTTP status code (e.g. 500).
reason (string) – HTTP reason phrase (e.g. “Internal Server Error”).
cimerror (string) – Value of the CIMError HTTP header field, if present. None, otherwise.
cimdetails (dict) –
Dictionary with CIMOM-specific header fields with details about the situation reported in the CIMError header field.
- Key: header field name (e.g. PGErrorDetail)
- Value: header field value (i.e. text message)
Passing None will result in an empty dictionary.
conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
request_data (string) – CIM-XML request string. None means the exception does not store a CIM-XML request.
response_data (string) – CIM-XML response string. None means the exception does not store a CIM-XML response.

Variables

args – A tuple (status, reason, cimerror, cimdetails) set from the corresponding init arguments.

Attributes:

`cimdetails`	CIMOM-specific details on the situation reported in the CIMError header field.
`cimerror`	Value of CIMError HTTP header field in response, if present.
`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`reason`	HTTP reason phrase.
`request_data`	CIM-XML request string (settable).
`response_data`	CIM-XML response string (settable).
`status`	HTTP status code.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

property cimdetails

CIMOM-specific details on the situation reported in the CIMError header field.

The value is a dictionary with:

Key: header field name (e.g. PGErrorDetail).
Value: header field value.

Type: dict

property cimerror

Value of CIMError HTTP header field in response, if present.

None, otherwise.

See DSP0200 for a list of values.

Type: string

property reason

HTTP reason phrase.

Example: “Internal Server Error”

See RFC2616 for a list of HTTP status codes and reason phrases.

Type: string

property status

HTTP status code.

Example: 500

See RFC2616 for a list of HTTP status codes and reason phrases.

Type: integer

class pywbem.TimeoutError(message, conn_id=None)[source]

This exception indicates that the client timed out waiting for the WBEM server.

Derived from Error.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.

Variables

args – A tuple (message, ) set from the corresponding init arguments.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.ParseError(message, conn_id=None, request_data=None, response_data=None)[source]

This exception is a base class for exceptions that indicate a parsing error with the CIM-XML operation response the pywbem client received, or with the CIM-XML indication request the pywbem listener received.

Derived from Error.

The CIM-XML response data is part of the str() representation of the exception.

This exception is a base class for more specific exceptions:

CIMXMLParseError - Issue at the CIM-XML level (e.g. NAME attribute missing on CLASS element)
XMLParseError - Issue at the XML level (e.g. ill-formed XML)
HeaderParseError - Issue with HTTP headers (e.g. invalid content-type header)

Occurrence of this exception nearly always indicates an issue with the WBEM server.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
request_data (string) – CIM-XML request string. None means the exception does not store a CIM-XML request.
response_data (string) – CIM-XML response string. None means the exception does not store a CIM-XML response.

Variables

args – A tuple (message, ) set from the corresponding init argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`request_data`	CIM-XML request string (settable).
`response_data`	CIM-XML response string (settable).

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.CIMXMLParseError(message, conn_id=None, request_data=None, response_data=None)[source]

This exception indicates a specific kind of ParseError that is an issue at the CIM-XML level.

Example: ‘NAME’ attribute missing on ‘CLASS’ element.

Occurrence of this exception nearly always indicates an issue with the WBEM server.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
request_data (string) – CIM-XML request string. None means the exception does not store a CIM-XML request.
response_data (string) – CIM-XML response string. None means the exception does not store a CIM-XML response.

Variables

args – A tuple (message, ) set from the corresponding init argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`request_data`	CIM-XML request string (settable).
`response_data`	CIM-XML response string (settable).

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.XMLParseError(message, conn_id=None, request_data=None, response_data=None)[source]

This exception indicates a specific kind of ParseError that is an issue at the XML level.

Example: Ill-formed XML.

Occurrence of this exception nearly always indicates an issue with the WBEM server.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
request_data (string) – CIM-XML request string. None means the exception does not store a CIM-XML request.
response_data (string) – CIM-XML response string. None means the exception does not store a CIM-XML response.

Variables

args – A tuple (message, ) set from the corresponding init argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`request_data`	CIM-XML request string (settable).
`response_data`	CIM-XML response string (settable).

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.HeaderParseError(message, conn_id=None, request_data=None, response_data=None)[source]

This exception indicates a specific kind of ParseError that is an issue with an HTTP header.

Example: Invalid content-type.

Occurrence of this exception nearly always indicates an issue with the WBEM server.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
request_data (string) – CIM-XML request string. None means the exception does not store a CIM-XML request.
response_data (string) – CIM-XML response string. None means the exception does not store a CIM-XML response.

Variables

args – A tuple (message, ) set from the corresponding init argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`request_data`	CIM-XML request string (settable).
`response_data`	CIM-XML response string (settable).

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.CIMError(status_code, status_description=None, instances=None, conn_id=None, request_data=None)[source]

This exception indicates that the WBEM server returned an error response with a CIM status code.

Derived from Error.

Accessing the CIM status code of a CIMError object:

In Python 2, any Exception object can be accessed by index and slice and will delegate such access to its args instance variable. In Python 3, that ability has been removed.

In pywbem 0.9, the status_code and status_description properties were added.

Therefore, the following approach is not recommended, because it does not work on Python 3:
except CIMError as exc:
    status_code = exc[0]
The following approach works for pywbem 0.7 or newer:
except CIMError as exc:
    status_code = exc.args[0]
The following approach is recommended when using pywbem 0.9 or newer:
except CIMError as exc:
    status_code = exc.status_code

Parameters

status_code (integer) – Numeric CIM status code.
status_description (string) – CIM status description text returned by the server, representing a human readable message describing the error. None, if the server did not return a description text.
instances (list of CIMInstance) – List of CIM instances returned by the WBEM server in the error response, that provide more details on the error. None if there are no such instances.
conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
request_data (string) – CIM-XML request string. None means the exception does not store a CIM-XML request.

Variables

args – A tuple (status_code, status_description, instances) set from the corresponding init arguments.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`instances`	CIM instances returned by the WBEM server in the error response, that provide more details on the error.
`request_data`	CIM-XML request string (settable).
`status_code`	Numeric CIM status code.
`status_code_name`	Symbolic name of the CIM status code.
`status_description`	CIM status description text returned by the server, representing a human readable message describing the error.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

property instances

CIM instances returned by the WBEM server in the error response, that provide more details on the error.

New in pywbem 0.13.

None if there are no such instances.

Type: List of CIMInstance

property status_code

Numeric CIM status code.

New in pywbem 0.9.

Example: 5

See CIM status codes for constants defining the numeric CIM status code values.

Type: integer

property status_code_name

Symbolic name of the CIM status code.

Example: “CIM_ERR_INVALID_CLASS”

New in pywbem 0.9.

If the CIM status code is invalid, the string “Invalid status code <status_code>” is returned.

Type: string

property status_description

CIM status description text returned by the server, representing a human readable message describing the error.

New in pywbem 0.9.

Example: “The specified class does not exist.”

If the server did not return a description, a short default text for the CIM status code is returned. If the CIM status code is invalid, the string “Invalid status code <status_code>” is returned.

Type: string

class pywbem.ModelError(message, conn_id=None)[source]

This exception indicates an error with the model implemented by the WBEM server, that was detected by the pywbem client.

Derived from Error.

Examples are mismatches in data types of CIM elements (properties, methods, parameters) between classes and instances, CIM elements that appear in instances without being declared in classes, or violations of requirements defined in advertised management profiles.

Parameters

message (string) – Error message (will be put into args[0]).
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.

Variables

args – A tuple (message, ) set from the corresponding init argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.Error(*args, **kwargs)[source]

Abstract base class for pywbem client specific exceptions.

Parameters

*args – Any other positional arguments are passed to Exception.
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known. Must be specified as a keyword argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

property conn_id

Connection ID of the connection in whose context the error happened.

None if the error did not happen in context of any connection, or if the connection context was not known.

Type: connection id

property conn_str

String that identifies the connection in exception messages.

Type: unicode string

Warnings

The following warnings are pywbem specific warnings that can be issued by the WBEM client library.

class pywbem.Warning(*args, **kwargs)[source]

Base class for pywbem specific warnings.

Parameters

*args – Any other positional arguments are passed to Exception.
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known. Must be specified as a keyword argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.ToleratedServerIssueWarning(*args, **kwargs)[source]

This warning indicates an issue with the WBEM server that has been tolerated by pywbem.

Parameters

*args – Any other positional arguments are passed to Exception.
conn_id (connection id) – Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known. Must be specified as a keyword argument.

Attributes:

`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

WBEM operation statistics

New in pywbem 0.11 as experimental and finalized in 0.12.

Pywbem supports measuring the elapsed times of the WBEM operations that were performed in context of a connection, and maintaining a statistics over these times.

This capability is disabled by default and can be enabled in either of these ways:

When creating a WBEMConnection object, via its stats_enabled argument.
After the WBEMConnection object has been created, by modifying its stats_enabled instance attribute.

The Statistics class maintains statistics over the measured elapsed times of the WBEM operations and is the interface for accessing the statistics. The statistics of a WBEMConnection object are accessible via its statistics instance attribute.

The OperationStatistic class is a helper class that contains the actual measurement data for one operation name. There will be one OperationStatistic object each operation name (see the table of WBEMConnection methods in the WBEM operations section for the operation names). The OperationStatistic objects are under control of the Statistics class.

The statistics support maintains two kinds of times for each kind of WBEM operation:

Client times: The elapsed times for the WBEMConnection operation methods from call to return. This is measured in pywbem pretty close to the API the pywbem user is calling.
Server times: The elapsed times for processing the WBEM operations in the WBEM server from receiving the CIM-XML request message to sending back the CIM-XML response message. The server times are not measured by pywbem, but are taken from the WBEMServerResponseTime HTTP header field of a CIM-XML response, if present. See DSP0200 for a description of this header field.

The WBEMServerResponseTime HTTP header field is optionally implemented by WBEM servers. The following WBEM servers are known to implement this header field:
- OpenPegasus
Because the interpretation of the calculated average and min/max server times becomes incorrect if only a subset of the operations return the server response time, the statistics counting for the server time is suspended if one or more operations do not return the server response time. Resetting the statistics via reset() clears this condition again.

The difference between client time and server time is the time spent in the pywbem client, plus the time spent on the network between client and server.

The statistics support also maintains the size of the HTTP body in the CIM-XML request and response messages, in Bytes.

These times and sizes are maintained as average, minimum and maximum values for each kind of operation in a connection.

Finally, the statistics support maintains the total count of operations and the count of operations that failed, for each kind of operation.

All data in the statistics applies to WBEM operations performed during periods of time where the statistics are enabled on a connection. Operations performed during periods of time where the statistics are disabled on a connection, are simply ignored in the statistics.

For the Iter methods of WBEMConnection (e.g. IterEnumerateInstances()), the WBEM operations performed on behalf of them are subject of the statistics, but the Iter methods themselves do not show up in the statistics.

The following example shows how statistics are enabled, and how statistics values are accessed individually using the get_op_statistic() method:

conn = pywbem.WBEMConnection(..., stats_enabled=True)

# Perform some operations on this connection
insts_1 = conn.EnumerateInstances('CIM_Foo1', 'root/cimv2')
insts_2 = conn.EnumerateInstances('CIM_Foo2', 'root/cimv2')
insts_3 = conn.EnumerateInstances('CIM_Foo3', 'root/cimv2')
inst_paths_1 = conn.EnumerateInstanceNames('CIM_Foo1', 'root/cimv2')

# Access statistics values for EnumerateInstances
ei_stats = conn.statistics.get_op_statistic('EnumerateInstances')
ei_count = ei_stats.count
ei_avg_client_time = ei_stats.avg_time
ei_avg_server_time = ei_stats.avg_server_time

In the previous example, the values in ei_stats are “live”, i.e. they continue to be updated as operations are performed. If a snapshot is needed at a certain point in time that remains unaffected by further operations, this can be achieved using the snapshot() method:

# Take snapshot and access statistics values for EnumerateInstances
stats_snapshot = dict(conn.statistics.snapshot())
ei_stats = stats_snapshot['EnumerateInstances']
ei_count = ei_stats.count
ei_avg_client_time = ei_stats.avg_time
ei_avg_server_time = ei_stats.avg_server_time

It is also possible to simply print the current statistics of a connection as a formatted table, using the formatted() method:

# Print statistics values for all operations
print(conn.statistics.formatted())

The output could look like this, if the WBEM server returns WBEM server response times:

Statistics (times in seconds, lengths in Bytes):
Count Excep         ClientTime              ServerTime             RequestLen                ReplyLen       Operation
        Cnt     Avg     Min     Max     Avg     Min     Max    Avg    Min    Max      Avg      Min      Max
    3     0   0.234   0.100   0.401   0.204   0.080   0.361   1233   1000   1500    26667    20000    35000 EnumerateInstances
    1     0   0.100   0.100   0.100   0.080   0.080   0.080   1200   1200   1200    22000    22000    22000 EnumerateInstanceNames

class pywbem.Statistics(enable=False)[source]

New in pywbem 0.11 as experimental and finalized in 0.12.

The statistics of a connection, that captures and provides statistics data about the WBEM operations performed on the connection.

This class contains an operation statistic object (of class OperationStatistic) for each kind of WBEM operation.

A Statistics object can be in a state of enabled or disabled. If enabled, it accumulates the elapsed times between subsequent calls to the start_timer() and stop_timer() methods of class OperationStatistic. If disabled, calls to these methods do not accumulate any time. Initially, the statistics container is disabled.

The enablement state of the Statistics object is controlled by the statistics enablement state of the connection it belongs to (see pywbem.WBEMConnection.stats_enabled())

This class can also be used as a context manager.

Parameters: enable (bool) – Initial enablement status for this statistics container.

Methods:

`__call__`(name)	This allows the name parameter to be passed when the class is used as a context manager.
`__enter__`()	Enter method when the class is used as a context manager.
`__exit__`(exc_type, exc_value, traceback)	Exit method when the class is used as a context manager.
`__repr__`()	Return a human readable display of the contents, for debug purposes.
`disable`()	Disable the statistics container.
`enable`()	Enable the statistics container.
`formatted`()	Return a human readable string with the statistics for this container.
`get_op_statistic`(name)	Get the `OperationStatistic` object for an operation name or create a new object if an object for that name does not exist.
`reset`()	Reset all statistics and clear any statistic names.
`snapshot`()	Return a snapshot of the time statistics of this container.
`start_timer`(name)	This method is called by pywbem to start the timer for a particular operation execution.

Attributes:

enabled

Indicates whether the statistics container is enabled.

__call__(name)[source]: This allows the name parameter to be passed when the class is used as a context manager.

__enter__()[source]

Enter method when the class is used as a context manager.

Starts the operation statistics for the name that was previously set via a call:

stats = Statistics()
with stats(name='bla'):
    # do something

The class supports nesting of context managers:

stats = Statistics()
with stats(name='bla1'):
    # do something
    for i in ...:
        with stats(name='bla2'):
            # do something

__exit__(exc_type, exc_value, traceback)[source]

Exit method when the class is used as a context manager.

Stops the operation statistics that was started in the enter method.

__repr__()[source]: Return a human readable display of the contents, for debug purposes.

disable()[source]: Disable the statistics container.

enable()[source]: Enable the statistics container.

property enabled: Indicates whether the statistics container is enabled.

formatted()[source]

Return a human readable string with the statistics for this container. The operations are sorted by decreasing average time.

The three columns for ServerTime are included only if the WBEM server has returned WBEM server response times for all operations.

The six columns for RequestLen and ReplyLen are included only if they are non-zero (this allows using this class for other purposes).

Example if statistics are enabled:

Statistics:
Count ExcCnt         Time [s]             ServerTime [s]        RequestLen [B]            ReplyLen [B]      Operation
                Avg     Min     Max     Avg     Min     Max    Avg    Min    Max      Avg      Min      Max
    3     0   0.234   0.100   0.401   0.204   0.080   0.361   1233   1000   1500    26667    20000    35000 EnumerateInstances
    1     0   0.100   0.100   0.100   0.080   0.080   0.080   1200   1200   1200    22000    22000    22000 EnumerateInstanceNames
    . . .

Example if statistics are disabled:

Statistics:
Disabled

get_op_statistic(name)[source]

Get the OperationStatistic object for an operation name or create a new object if an object for that name does not exist.

Parameters: name (string) – Name of the operation.
Returns: The operation statistic for the specified operation name. If this statistics container is disabled, a dummy operation statistic object is returned.
Return type: OperationStatistic

reset()[source]

Reset all statistics and clear any statistic names. All statistics must be inactive before a reset will execute

Returns: True if reset, False if not

snapshot()[source]

Return a snapshot of the time statistics of this container.

The snapshot represents the statistics data at the time this method is called, and remains unchanged even if the statistics of this container continues to be updated.

Returns

A list of tuples (name, stats) with:

name (string): Name of the operation
stats (OperationStatistic): Time statistics for the operation

start_timer(name)[source]

This method is called by pywbem to start the timer for a particular operation execution. It returns the corresponding OperationStatistic object, creating one if needed.

The timer is subsequently stopped by pywbem by calling the stop_timer() method on the returned OperationStatistic object.

Parameters: name (string) – Name of the operation.
Returns: The operation statistic for the specified name. If this statistics container is disabled, a dummy operation statistic object is returned.
Return type: OperationStatistic

class pywbem.OperationStatistic(container, name)[source]

New in pywbem 0.11 as experimental and finalized in 0.12.

A statistics data keeper for the executions of all operations with the same operation name.

Objects of this class are created by the Statistics class and can be accessed by pywbem users through its get_op_statistic() and snapshot() methods.

Parameters

container (Statistics) – The statistics container that holds this operation statistic object.
name (string) – Name of the operation.

Methods:

`__repr__`()	Return a human readable string with the statistics values, for debug purposes.
`formatted`(include_server_time, include_lengths)	Return a formatted one-line string with the statistics values for the operation for which this statistics object maintains data.
`formatted_header`(include_server_time, ...)	Return a two-line header.
`reset`()	Reset the statistics data for this object.
`start_timer`()	This is a low-level method that is called by pywbem at the begin of an operation.
`stop_timer`([request_len, reply_len, ...])	This is a low-level method is called by pywbem at the end of an operation.

Attributes:

`avg_reply_len`	The average size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
`avg_request_len`	The average size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
`avg_server_time`	The average elapsed server time for execution of the measured operations, in seconds.
`avg_time`	The average elapsed client time for execution of the measured operations, in seconds.
`container`	The statistics container that holds this statistics object.
`count`	The number of measured operations.
`exception_count`	The number of measured operations that resulted in an exception returned to the pywbem user (for example because a failure was indicated in the operation response of the WBEM server, or because pywbem itself detected a failure before sending the request or after receiving the response).
`max_reply_len`	The maximum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
`max_request_len`	The maximum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
`max_server_time`	The maximum elapsed server time for execution of the measured operations, in seconds.
`max_time`	The maximum elapsed client time for execution of the measured operations, in seconds.
`min_reply_len`	The minimum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
`min_request_len`	The minimum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
`min_server_time`	The minimum elapsed server time for execution of the measured operations, in seconds.
`min_time`	The minimum elapsed client time for execution of the measured operations, in seconds.
`name`	Name of the operation for which this statistics object maintains data.
`stat_start_time`	Point in time when the first statistic was taken since this object was either created or reset, in seconds since the epoch (for details, see `time.time()`).

__repr__()[source]: Return a human readable string with the statistics values, for debug purposes.

property avg_reply_len

The average size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.

Type: float

property avg_request_len

The average size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.

Type: float

property avg_server_time

The average elapsed server time for execution of the measured operations, in seconds.

This time is 0 if the WBEM server did not return the WBEM server response time.

Type: float

property avg_time

The average elapsed client time for execution of the measured operations, in seconds.

Type: float

property container

The statistics container that holds this statistics object.

Type: Statistics

property count

The number of measured operations.

Type: integer

property exception_count

The number of measured operations that resulted in an exception returned to the pywbem user (for example because a failure was indicated in the operation response of the WBEM server, or because pywbem itself detected a failure before sending the request or after receiving the response).

Type: integer

formatted(include_server_time, include_lengths)[source]

Return a formatted one-line string with the statistics values for the operation for which this statistics object maintains data.

This is a low-level method that is called by pywbem.Statistics.formatted().

static formatted_header(include_server_time, include_lengths)[source]: Return a two-line header.

property max_reply_len

The maximum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.

Type: float

property max_request_len

The maximum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.

Type: float

property max_server_time

The maximum elapsed server time for execution of the measured operations, in seconds.

This time is 0 if the WBEM server did not return the WBEM server response time.

Type: float

property max_time

The maximum elapsed client time for execution of the measured operations, in seconds.

Type: float

property min_reply_len

The minimum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.

Type: float

property min_request_len

The minimum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.

Type: float

property min_server_time

The minimum elapsed server time for execution of the measured operations, in seconds.

This time is 0 if the WBEM server did not return the WBEM server response time.

Type: float

property min_time

The minimum elapsed client time for execution of the measured operations, in seconds.

Type: float

property name

Name of the operation for which this statistics object maintains data.

Type: string

reset()[source]: Reset the statistics data for this object.

start_timer()[source]

This is a low-level method that is called by pywbem at the begin of an operation. It starts the measurement for that operation, if statistics is enabled for the connection.

A subsequent invocation of stop_timer() will complete the measurement for that operation and will update the statistics data.

property stat_start_time

Point in time when the first statistic was taken since this object was either created or reset, in seconds since the epoch (for details, see time.time()).

Type: float

stop_timer(request_len=None, reply_len=None, server_time=None, exception=False)[source]

This is a low-level method is called by pywbem at the end of an operation. It completes the measurement for that operation by capturing the needed data, and updates the statistics data, if statistics is enabled for the connection.

Parameters

request_len (integer) – Size of the HTTP body of the CIM-XML request message, in Bytes.
reply_len (integer) – Size of the HTTP body of the CIM-XML response message, in Bytes.
exception (bool) – Boolean that specifies whether an exception was raised while processing the operation.
server_time (bool) –
Time in seconds that the server optionally returns to the client in the HTTP response defining the time from when the server received the request to when it started sending the response.

If None, the server did not report server response time. Since this can happen in the middle of a statistics measurement interval if the corresponding config setting of the server was changed, the server time is then reset to 0 and no longer maintained during the remainder of the current statistics measurement interval. A reset of the statistics clears that condition again.

Returns

The elapsed time for the operation that just ended, or None if the statistics container holding this object is not enabled.

Return type

float

WBEM operation logging

New in pywbem 0.11 and redesigned in pywbem 0.12. Finalized in pywbem 0.13.

Pywbem logging overview

The pywbem package implements selected logging using the Python logging facility. This section describes logging for use of the pywbem package as a WBEM client. Section Logging in the listener describes logging for use of the pywbem package as a WBEM listener.

Pywbem logging is used to record information passing between the pywbem client and WBEM servers but not as a general recorder for errors, state, etc. within pywbem. In effect it is a trace tool. Pywbem errors are generally passed to the pywbem API user as Python exceptions rather than being recorded in a log by a pywbem logger.

Pywbem logging uses two Python Logger objects which are termed pywbem loggers:

API logger (Python logger name: ‘pywbem.api’) - Logs API calls and returns, for the WBEMConnection methods that drive WBEM operations (see WBEM operations). This logs the API parameters and results, including CIM objects/exceptions. It also logs the creation of WBEMConnection objects to capture connection information in order to determine the connection to which a particular log record belongs.
HTTP logger (Python logger name: ‘pywbem.http’) - Logs HTTP requests and responses between the pywbem client and WBEM server. This logs the HTTP request data and response data including HTTP headers and CIM-XML payload.

Pywbem uses the DEBUG logging level (see Logging Levels) for both loggers.

Pywbem adds a null handler to the logger named ‘pywbem’, in order to prevent the “No handlers could be found for logger …” warning. This follows best practices recommended in Configuring logging for a library and in several articles, for example in this article. Because this warning is no longer issued on Python 3.4 and higher, pywbem adds a null handler only on Python 2.7.

Because pywbem logs only at the DEBUG logging level (see Logging Levels), these log events will not be printed by the Python root logger by default, and therefore it is not necessary that pywbem attaches a null handler to any of its loggers.

There are two steps to setting up pywbem logging:

Configure Python logging parameters

Sets the Python logging parameters for a pywbem logger or its parent loggers, such as log handler, message format, and logging level.

This can be done with Python logging functions or with the functions described in Logging configuration functions.
Activate WBEM connection(s) for logging and set detail level

In order to save the cycles for capturing the possibly large amounts of data needed for creating the log records, pywbem logging is inactive by default. Logging can be activated for an existing WBEM connection, or for all subsequently created WBEM connections.

Because the pywbem loggers can generate large quantities of information, the user can control the quantity of information produced by each pywbem logger by setting a detail level for each logger when activating a WBEM connection for logging.

Activation and setting detail levels are pywbem features so it requires using the functions described in Logging configuration functions.

Logging configuration functions

The pywbem loggers may be configured and/or WBEM connections may be activated for logging through the following pywbem functions.

These functions are the only mechanism for setting the detail level of a pywbem logger and for activating WBEM connection(s) for logging.

configure_logger() - Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level.
configure_loggers_from_string() - Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level, from a log configuration string.

This is most useful in defining the pywbem logging from a command line tool such as pywbemcli so the complete logger configuration can be compressed into a single command line string.

Logging configuration examples

Examples for using configure_logger() for configuring pywbem loggers and for activating WBEM connections for logging:

Example: Configure the ‘pywbem.api’ logger with detail level ‘summary’ and output to stderr, and activate all subsequently created WBEM connections for logging:

configure_logger('api', log_dest='stderr', detail_level='summary',
                 connection=True)

# All of the following connections will log to stderr with summary output:
conn1 = WBEMConnection(...)
conn2 = WBEMConnection(...)

Example: Configure all pywbem loggers with the default detail level (‘all’) and output to a file, and activate a single existing WBEM connection for logging:
```
conn = WBEMConnection(...)

configure_logger('all', log_dest='file', log_filname='my_logfile.log',
                 connection=conn)
```

Examples for configuring the pywbem loggers using Python logging methods, and using the pywbem logging configuration functions only for setting the detail level and for activating WBEM connections for logging:

Example: Configure the pywbem parent logger (named ‘pywbem’) for logging to a rotating file, configure both pywbem loggers for detail level ‘summary’, and activate all subsequent WBEM connections for logging:

import logging
from logging.handlers import RotatingFileHandler

logger = logging.getLogger('pywbem')
handler = RotatingFileHandler("my_log.log", maxBytes=2000, backupCount=10)
handler.setLevel(logging.DEBUG)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

# configure without setting log_dest
configure_logger('api', detail_level='summary', connection=True)

# All of the following connections will log using the rotating file handler:
conn1 = WBEMConnection(...)
conn2 = WBEMConnection(...)

Examples for using configure_loggers_from_string() for configuring the pywbem loggers and for activating WBEM connections for logging:

Example: Configure the ‘pywbem.api’ logger with detail level ‘summary’, output to stderr, and activate all subsequently created WBEM connections for logging:

configure_loggers_from_string('api=stderr:summary', connection=True)

# All of the following connections will log:
conn1 = WBEMConnection(...)
conn2 = WBEMConnection(...)

Example: Configure both pywbem loggers with the default detail level (‘all’) and output to the file ‘my_log.log’, and activate a single existing WBEM connection object (conn) for logging:
```
conn = WBEMConnection(...)

configure_loggers_from_string('all=file', log_filname='my_log.log',
                              connection=conn)
```

Log records

The following is an example of log output with detail level ‘summary’, where ‘1-32073’ is the connection identifier:

2018-03-17 11:39:09,877-pywbem.api.1-32073-Connection:1-32073 WBEMConnection(url='http://localhost', creds=None, default_namespace='root/cimv2')
2018-03-17 11:41:13,176-pywbem.api.1-32073-Request:1-32073 EnumerateClasses(ClassName=None, DeepInheritance=None, IncludeClassOrigin=None, IncludeQualifiers=None, LocalOnly=None, namespace=None)
2018-03-17 11:41:13,635-pywbem.api.1-32073-Return:1-32073 EnumerateClasses(list of CIMClass; count=103)

The keywords in each log record (‘Connection’, ‘Request’, ‘Return’ or ‘Exception’) identify whether the log record is connection data, API/HTTP request data, API/HTTP response data, or API exception data.

The loggers that actually create the log records are children of the configured pywbem loggers and are unique for each WBEMConnection object. Their logger names are created from the configured logger names by appending the connection identifier (conn_id). Thus the names of the loggers that actually create the log records are of the form: ‘pywbem.<api/http>.<conn_id>’.

Data:

`DEFAULT_LOG_DESTINATION`	Default log destination if not supplied to the logging configuration functions.
`DEFAULT_LOG_DETAIL_LEVEL`	Default log detail level if not supplied to the logging configuration functions.
`DEFAULT_LOG_FILENAME`	Default path name of the log file to be used when logging to a file.
`LOGGER_API_CALLS_NAME`	Name of the pywbem API logger, which logs user-issued calls to and returns from `WBEMConnection` methods that drive WBEM operations.
`LOGGER_HTTP_NAME`	Name of the pywbem HTTP logger, which logs HTTP requests and responses between the pywbem client and WBEM servers.
`LOGGER_SIMPLE_NAMES`	List of the simple pywbem logger names that the logging configuration functions (see Logging configuration functions) recognize, as follows:
`LOG_DESTINATIONS`	List of log destinations that the logging configuration functions recognize, as follows:
`LOG_DETAIL_LEVELS`	List of the log detail levels that the logging configuration functions recognize, as follows:

Functions:

`configure_logger`(simple_name[, log_dest, ...])	Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level.
`configure_loggers_from_string`(...[, ...])	Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level, from a log configuration string.

pywbem._logging.DEFAULT_LOG_DESTINATION = 'file': Default log destination if not supplied to the logging configuration functions.

pywbem._logging.DEFAULT_LOG_DETAIL_LEVEL = 'all': Default log detail level if not supplied to the logging configuration functions.

pywbem._logging.LOGGER_API_CALLS_NAME = 'pywbem.api': Name of the pywbem API logger, which logs user-issued calls to and returns from WBEMConnection methods that drive WBEM operations.

pywbem._logging.LOGGER_HTTP_NAME = 'pywbem.http': Name of the pywbem HTTP logger, which logs HTTP requests and responses between the pywbem client and WBEM servers.

pywbem._logging.LOGGER_SIMPLE_NAMES = ['api', 'http', 'all']

List of the simple pywbem logger names that the logging configuration functions (see Logging configuration functions) recognize, as follows:

‘api’ - Pywbem API logger (Python logger name: ‘pywbem.api’)
‘http’ - Pywbem HTTP logger (Python logger name: ‘pywbem.http’)
‘all’ - All pywbem loggers

pywbem._logging.LOG_DESTINATIONS = ['file', 'stderr', 'off']

List of log destinations that the logging configuration functions recognize, as follows:

‘file’ - Log to a file (requires filename to be specified). The file logger appends to the logger file defined by filename.
‘stderr’ - Log to the standard error stream of the Python process.
‘off’ - Disable logging.

pywbem._logging.LOG_DETAIL_LEVELS = ['all', 'paths', 'summary']

List of the log detail levels that the logging configuration functions recognize, as follows:

‘all’ - All of the data available is output. Generally this is the repr() output of the objects in the requests and responses.
‘paths’ - For the API logger, for operations that return CIM classes or CIM instances, only their path component is output as a WBEM URI string. Otherwise, all of the data available is output.
‘summary’ - Only summary information is output. For the API logger this is primarily the count and type of objects returned. For the HTTP logger the HTTP header information is output.

pywbem._logging.configure_logger(simple_name, log_dest=None, detail_level='all', log_filename='pywbem.log', connection=None, propagate=False)[source]

Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level.

Parameters

simple_name (string) –
Simple name (ex. ‘api’) of the single pywbem logger this method should affect, or ‘all’ to affect all pywbem loggers.

Must be one of the strings in LOGGER_SIMPLE_NAMES.
log_dest (string) –
Log destination for the affected pywbem loggers, controlling the configuration of its Python logging parameters (log handler, message format, and log level).

If it is a string, it must be one of the strings in LOG_DESTINATIONS and the Python logging parameters of the loggers will be configured accordingly for their log handler, message format, and with a logging level of DEBUG (see Logging Levels).

The value ‘off’ disables logging for the affected pywbem loggers.

If None, the Python logging parameters of the loggers will not be changed.
detail_level (string or int or None) –
Detail level for the data in each log record that is generated by the affected pywbem loggers.

If it is a string, it must be one of the strings in LOG_DETAIL_LEVELS and the loggers will be configured for the corresponding detail level.

If it is an int, it defines the maximum size of the log records created and the loggers will be configured to output all available information up to that size.

If None, the detail level configuration will not be changed.
log_filename (string) – Path name of the log file (required if the log destination is ‘file’; otherwise ignored).
connection (WBEMConnection or bool or None) –
WBEM connection(s) that should be affected for activation and for setting the detail level.

If it is a bool, the information for activating logging and for the detail level of the affected loggers will be stored for use by subsequently created WBEMConnection objects. A value of True will store the information to activate the connections for logging, and will add the detail level for the logger(s). A value of False will reset the stored information for future connections to be deactivated with no detail levels specified.

If it is a WBEMConnection object, logging will be activated for that WBEM connection only and the specified detail level will be set for the affected pywbem loggers on the connection.

If None, no WBEM connection will be activated for logging.
propagate (bool) – Flag controlling whether the affected pywbem logger should propagate log events to its parent loggers.

Raises

ValueError – Invalid input parameters (loggers remain unchanged).

pywbem._logging.configure_loggers_from_string(log_configuration_str, log_filename='pywbem.log', connection=None, propagate=False)[source]

Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level, from a log configuration string.

This is most useful in defining the loggers from a command line tool such as pywbemcli so the complete logger configuration can be compressed into a single command line string.

Parameters

log_configuration_str (string) –
The log configuration string, in the following format:
```
log_specs := log_spec [ ',' log_spec ]
log_spec := logger_simple_name [ '=' [ log_dest ] [ ":" [ detail_level ]]]]
```
where:
- logger_simple_name: Simple logger name. Must be one of the strings in the LOGGER_SIMPLE_NAMES list.
- log_dest: Log destination. Must be one of the strings in the LOG_DESTINATIONS list. Default is DEFAULT_LOG_DESTINATION.
- detail_level: Log detail level. Must be one of the strings in the LOG_DETAIL_LEVELS list. Default is DEFAULT_LOG_DETAIL_LEVEL.
log_filename (string) – Path name of the log file (required if any log destination is ‘file’; otherwise ignored).
connection (WBEMConnection or bool or None) –
WBEM connection(s) that should be affected for activation and for setting the detail level.

If it is a bool, the information for activating logging and for the detail level of the affected loggers will be stored for use by subsequently created WBEMConnection objects. A value of True will store the information to activate the connections for logging, and will add the detail level for the logger(s). A value of False will reset the stored information for future connections to be deactivated with no detail levels specified.

If it is a WBEMConnection object, logging will be activated for that WBEM connection only and the specified detail level will be set for the affected pywbem loggers on the connection.

If None, no WBEM connection will be activated for logging.
propagate (bool) – Flag controlling whether the affected pywbem logger should propagate log events to its parent loggers.

Raises

ValueError – Invalid input parameters (loggers remain unchanged).

Examples for log_configuration_str:

'api=stderr:summary'    # Set 'pywbem.api' logger to stderr output with
                        # summary detail level.

'http=file'             # Set 'pywbem.http' logger to file output with
                        # default detail level.

'api=stderr:summary'    # Set 'pywbem.api' logger to file output with
                        # summary output level.

'all=file:1000'         # Set both pywbem loggers to file output with
                        # a maximum of 1000 characters per log record.

'api=stderr,http=file'  # Set 'pywbem.api' logger to stderr output and
                        # 'pywbem.http' logger to file output, both
                        # with default detail level.

'all=off'               # Disables logging for both pywbem loggers.

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.

Support for PUnit and Units qualifiers

The pywbem.siunit_obj() and pywbem.siunit() functions translate the PUnit and Units qualifier values into human readable SI conformant unit strings.

New in pywbem 1.1 as experimental and finalized in 1.3.

Note: These functions do not perform any class operations; they take the qualifiers as input.

The reason the Units qualifier is still supported is that the DMTF CIM Schema (as of its version 2.49) still contains a number of schema elements that have the Units qualifier but not the PUnit qualifier set.

The format and valid base units for the PUnit qualifier and the valid values for the Units qualifier are defined in Annex C of DSP0004. Pywbem supports the definitions from DSP0004 version 2.8, with two extensions:

Pywbem supports the following additional Units qualifier values that are used in the DMTF CIM Schema (as of its version 2.49) but are not defined in DSP0004:

Additional `Units` values
`-dBm`
`Blocks`
`Percentage`
`Proportion`
`Tenths of Revolutions per Minute`

Pywbem supports a slightly more flexible version of the PUnit format that is used in DMTF CIM Schema version 2.49 but not defined in DSP0004: The numeric element may appear anywhere in the formula and not just at the end.

By default, the string value returned from these functions may contain the following Unicode characters outside of the 7-bit ASCII range. If the use_ascii parameter is True, these Unicode characters are replaced with 7-bit ASCII text as follows:

Unicode character code	Unicode	7-bit ASCII
U+00B0: DEGREE SIGN	`°`	`deg`
U+00B5: MICRO SIGN	`µ`	`u`
U+2030: PER MILLE SIGN	`‰`	`1/1000`
U+2126: OHM SIGN	`Ω`	`Ohm`
U+00B2: SUPERSCRIPT TWO	`²`	`^2`
U+00B3: SUPERSCRIPT THREE	`³`	`^3`

Examples:

PUnit("byte / second * 10^3") -> kB/s
PUnit("byte * 2^10") -> KiB
PUnit("hertz * 10^6") -> MHz
PUnit("ampere * 10^-3") -> mA
Units("KiloBits per Second") -> kbit/s
Units("Tenths of Degrees C") -> 1/10 °C

Limitations:

For PUnit qualifiers, vendor-defined base units are not supported (e.g. vendor:myunit).
For PUnit qualifiers, space characters within the parenthesis of decibel (e.g. decibel ( A )) are not supported.
For Units qualifiers, arbitrary numeric values that are part of the Units value (e.g. <numeric-value> NanoSeconds or Amps at <numeric-value> Volts) are not generally supported, but only for those cases that are used in the DMTF CIM Schema (as of its version 2.49):
- 250 NanoSeconds
- Amps at 120 Volts

pywbem.siunit_obj(cim_obj, use_ascii=False)[source]

Returns a human readable SI conformant unit string from the PUnit or Units qualifiers of the specified CIM object.

New in pywbem 1.1 as experimental and finalized in 1.3.

If the CIM object has both the PUnit and Units qualifiers set, then PUnit is used and Units is ignored.

Parameters

cim_obj (CIMProperty or CIMMethod or CIMParameter) – CIM object with qualifiers.
use_ascii (bool) – Replace any Unicode characters in the returned string with 7-bit ASCII replacements, as described above.

Returns

Human readable SI conformant unit string, or None if the CIM object has neither the PUnit nor the Units qualifiers set.

Return type

Raises

TypeError – Invalid type for cim_obj
ValueError – Invalid format in PUnit qualifier
ValueError – Unknown base unit in PUnit qualifier
ValueError – Unknown unit in Units qualifier

Example:

>>> cls = conn.GetClass("CIM_StorageSetting", IncludeQualifiers=True)
>>> prop = cls['InterconnectSpeed']
>>> print(pywbem.siunit_obj(prop))
bit/s

pywbem.siunit(punit=None, units=None, use_ascii=False)[source]

Returns a human readable SI conformant unit string from the specified PUnit or Units qualifier values.

New in pywbem 1.1 as experimental and finalized in 1.3.

If both punit and units are specified, then punit is used and units is ignored.

Parameters

punit (string) – Value of the PUnit qualifier, or None.
units (string) – Value of the Units qualifier, or None.
use_ascii (bool) – Replace any Unicode characters in the returned string with 7-bit ASCII replacements, as described above.

Returns

Human readable SI conformant unit string, or None if both qualifier value input parameters were None.

Return type

Raises

TypeError – Invalid type for punit or unit
ValueError – Invalid format in PUnit qualifier
ValueError – Unknown base unit in PUnit qualifier
ValueError – Unknown unit in Units qualifier

Examples:

>>> print(pywbem.siunit(punit="byte / second * 10^3"))
kB/s
>>> print(pywbem.siunit(punit="byte * 2^10"))
KiB
>>> print(pywbem.siunit(punit="hertz * 10^6"))
MHz
>>> print(pywbem.siunit(punit="ampere * 10^-3"))
mA
>>> print(pywbem.siunit(units="KiloBits per Second"))
kbit/s
>>> print(pywbem.siunit(units="Tenths of Degrees C"))
1/10 °C
>>> print(pywbem.siunit(units="Tenths of Degrees C", use_ascii=True))
1/10 degC

Security considerations

Authentication types

Authentication is the act of establishing the identity of a user on the client side to the server, and possibly also of establishing the identity of a server to the client.

There are two levels of authentication in CIM-XML:

TLS/SSL level authentication (only when HTTPS is used):

This kind of authentication is also known as transport level authentication. It is used during the TLS/SSL handshake protocol, before any HTTP requests flow.

In almost all cases (unless an anonymous cipher is used), this involves an X.509 certificate that is presented by the server (therefore called server certificate) and that allows the client to establish the identity of the server.

It optionally involves an X.509 certificate that is presented by the client (therefore called client certificate) and that allows the server to establish the identity of the client or even of the client user, and thus can avoid the use of credentials in the HTTP level authentication.

If a client certificate is used, the authentication scheme at the TLS/SSL level is called 2-way authentication (also known as client authentication or mutual SSL authentication). If a client certificate is not used, the authentication scheme is called 1-way authentication (also known as SSL authentication).

Userid/password credentials do not play any role in TLS/SSL level authentication.
HTTP level authentication:

This kind of authentication is used in HTTP/HTTPS requests and responses (in case of HTTPS, after the TLS/SSL handshake protocol has completed).

In case of Basic Authentication and Digest Authentication (see RFC2617), it involves passing credentials (userid and password) via the Authenticate and WWW-Authenticate HTTP headers. In case of no authentication, credentials are not passed.

A client can either provide the Authenticate header along with a request, hoping that the server supports the authentication scheme that was used.

A client can also omit that header in the request, causing the server to send an error response with a WWW-Authenticate header that tells the client which authentication types are supported by the server (also known as a challenge). The client then repeats the first request with one of the supported authentication types.

HTTP is extensible w.r.t. authentication schemes, and so is CIM-XML. However, pywbem only supports Basic Authentication and no authentication.

X.509 certificates do not play any role in HTTP level authentication.

HTTP/HTTPS knows a third level of authentication by the use of session cookies. CIM-XML does not define how cookies would be used, and pywbem does not deal with cookies in any way (i.e. it does not pass cookies provided in a response into the next request).

The following table shows the possible combinations of protocol, TLS/SSL level and HTTP level authentication schemes, which information items need to be provided to the WBEM client library, and whether the combination is supported by pywbem:

Protocol	SSL auth.	HTTP auth.	Credentials	Client cert.	CA cert.	Supported
HTTP	N/A	None	No	No	No	Yes (1)
HTTP	N/A	Basic	Yes	No	No	Yes (2)
HTTP	N/A	Digest	Yes	No	No	No
HTTPS	1-way	None	No	No	Yes (3)	Yes (1)
HTTPS	1-way	Basic	Yes	No	Yes (3)	Yes
HTTPS	1-way	Digest	Yes	No	Yes (3)	No
HTTPS	2-way	None	No	Yes	Yes (3)	Yes (4)
HTTPS	2-way	Basic	Yes	Yes	Yes (3)	Yes
HTTPS	2-way	Digest	Yes	Yes	Yes (3)	No

Notes:

This option does not allow a server to establish the identity of the user. Its use should be limited to environments where network access is secured.
The use of HTTP Basic Authentication is strongly discouraged, because the password is sent unencrypted over the network.
A CA certificate is needed, unless server certificate verification is disabled via the no_verification parameter (not recommended), or unless an anonymous cipher is used for the server certificate (not recommended).
This is the most desirable option from a security perspective, if the WBEM server is able to establish the user identity based on the client certificate.

The protocol and authentication types that can be used on a connection to a WBEM server are set by the user when creating the WBEMConnection object:

The scheme of the URL in the url parameter controls whether the HTTP or HTTPS protocol is used.
The cred parameter may specify credentials (userid/password). If specified, pywbem uses them for Basic Authentication at the HTTP level. Pywbem provides an Authenticate HTTP header on each request, and also handles server challenges transparently to the user of the WBEM client library, by retrying the original request.
The x509 parameter may specify an X.509 client certificate and key. If specified, pywbem uses 2-way authentication; otherwise it uses 1-way authentication at the TLS/SSL level.
The ca_certs parameter controls which X.509 CA certificates are used to validate the X.509 server certificate returned by the WBEM server.

It is important to understand which side actually makes decisions about security-related parameters: The client only decides whether HTTP or HTTPS is used, and whether the server certificate is verified. The server decides everything else: Which HTTP authentication scheme is used (None, Basic, Digest), whether an X.509 client certificate is requested from the client and if so, whether it tolerates a client not providing one. In addition, when HTTPS is used, the client proposes cipher suites it supports, and the server picks one of them.

Therefore, the cred and x509 parameters do not control the authentication scheme that is actually used, but merely prepare pywbem to deal with whatever authentication scheme the WBEM server elects to use.

WBEM servers typically support corresponding configuration parameters.

Verification of the X.509 server certificate

When using HTTPS, the TLS/SSL handshake protocol requires that the server always returns an X.509 server certificate to the client (unless anonymous ciphers are used, which is not recommended).

Pywbem uses the requests Python package for communicating with the WBEM server, and thus delegates the validation of the server certificate to OpenSSL.

If the validation of the server certificate fails, the WBEM operation methods of the WBEMConnection object raise pywbem.ConnectionError with an according error message.

Validation of the server certificate can be disabled via the no_verification parameter of WBEMConnection. Disabling certificate validation makes the communication of pywbem with the WBEM server vulnerable to man-in-the-middle attacks, because the identity of the server cannot be verified.

Use of X.509 client certificates

When using HTTPS, the TLS/SSL handshake protocol provides the option for the client to present an X.509 certificate to the server (therefore called client certificate).

This procedure is initiated by the server, by requesting that the client present a client certificate. If the client does not have one (for example, because the x509 parameter was not specified in pywbem), it must send an empty list of certificates to the server. Depending on the server configuration, the server may or may not accept an empty list. If a client certificate is presented, the server must validate it.

The server can support to accept the user identity specified in the client certificate as the user’s identity, and refrain from sending HTTP challenges that request credentials.

Authentication errors

The operation methods of WBEMConnection raise pywbem.AuthError when the WBEM server returns HTTP status 401 “Unauthorized” and the retries in the client are exhausted. The server typically returns that status in any of these situations:

invalid credentials provided by client
no credentials provided by client but server requires them
user is not authorized to access a resource
server does not support the HTTP authentication scheme used by the client. Pywbem uses the “Basic” authentication scheme, which is recommended in DSP0200.

Proxy support

Starting with version 1.0, pywbem supports HTTP and SOCKS 5 proxies for connecting to the WBEM server. This is done by utilizing the proxy support in the underlying requests Python package.

The proxies to be used can be specified using the proxies init argument of WBEMConnection, or via the environment variables HTTP_PROXY and HTTPS_PROXY.

If the proxies init argument is not None, it takes precedence over the environment variables and must be a dictionary with item keys ‘http’ and ‘https’. Each item value specifies the URL of the proxy that is to be used for the WBEM server protocol specified by the key.

In case of the environment variables, the value of HTTP_PROXY and HTTPS_PROXY specify the URL of the proxy that is to be used for the http and https WBEM server protocol, respectively.

If the proxy support is used, the url init argument of WBEMConnection specifies the connection properties the proxy uses for connecting to the WBEM server. The no_verification, ca_certs, and x509 init arguments are also applied to the connection between the proxy and the WBEM server. The URL of the proxy specified via the proxies init argument or via the HTTP_PROXY and HTTPS_PROXY environment variables is what the pywbem client uses to connect to the proxy.

The following examples show some typical cases and are not exhaustive. For the full description of what is possible, refer to the Proxies section in the documentation of the requests package. In these examples, the proxy URLs are specified using the proxies init argument, but they can also be specified using the HTTP_PROXY and HTTPS_PROXY environment variables.

Use of an HTTP proxy requiring authentication:

proxies = {
  'http': 'http://user:pass@10.10.1.10:3128',
  'https': 'http://user:pass@10.10.1.10:1080',
}

conn = pywbem.WBEMConnection(..., proxies=proxies)

Use of SOCKS proxies requires installing the socks option of the requests Python package:

$ pip install requests[socks]

Use of a SOCKS 5 proxy requiring authentication where the DNS resolution for the WBEM server hostname is done on the client (where pywbem runs):

proxies = {
  'http': 'socks5://user:pass@10.10.1.10:3128',
  'https': 'socks5://user:pass@10.10.1.10:1080',
}

conn = pywbem.WBEMConnection(..., proxies=proxies)

Use of a SOCKS 5 proxy requiring authentication where the DNS resolution for the WBEM server hostname is done on the proxy:

proxies = {
  'http': 'socks5h://user:pass@10.10.1.10:3128',
  'https': 'socks5h://user:pass@10.10.1.10:1080',
}

conn = pywbem.WBEMConnection(..., proxies=proxies)

WBEM server library

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEM server library API of pywbem encapsulates selected functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace and other basic information about the server, or the management profiles advertised by the server.

This chapter has the following sections:

Example - An example on how to use the WBEM server library API.
WBEMServer - The WBEMServer class serves as a general access point for clients to WBEM servers. It allows determining the Interop namespace of the server and other basic information about the server, or the advertised management profiles.

Example

The following example code displays some information about a WBEM server:

from pywbem import WBEMConnection, WBEMServer, ValueMapping

def explore_server(server_url, username, password):

    print("WBEM server URL:\n  {0}".format(server_url))

    conn = WBEMConnection(server_url, (username, password))
    server = WBEMServer(conn)

    print("Brand:\n  {0}".format(server.brand))
    print("Version:\n  {0}".format(server.version))
    print("Interop namespace:\n  {0}".format(server.interop_ns))

    print("All namespaces:")
    for ns in server.namespaces:
        print("  {0}".format(ns))

    print("Advertised management profiles:")
    org_vm = ValueMapping.for_property(server, server.interop_ns,
        'CIM_RegisteredProfile', 'RegisteredOrganization')
    for inst in server.profiles:
        org = org_vm.tovalues(inst['RegisteredOrganization'])
        name = inst['RegisteredName']
        vers = inst['RegisteredVersion']
        print("  {0} {1} Profile {2}".format(org, name, vers))

Example output:

WBEM server URL:
  http://0.0.0.0
Brand:
  OpenPegasus
Version:
  2.12.0
Interop namespace:
  root/PG_Interop
All namespaces:
  root/PG_InterOp
  root/PG_Internal
  root/cimv2
  root
Advertised management profiles:
  SNIA Indication Profile 1.1.0
  SNIA Indication Profile 1.2.0
  SNIA Software Profile 1.1.0
  SNIA Software Profile 1.2.0
  SNIA Profile Registration Profile 1.0.0
  SNIA SMI-S Profile 1.2.0
  SNIA Server Profile 1.1.0
  SNIA Server Profile 1.2.0
  DMTF Profile Registration Profile 1.0.0
  DMTF Indications Profile 1.1.0

WBEMServer

class pywbem.WBEMServer(conn)[source]

New in pywbem 0.9 as experimental and finalized in 0.10.

A representation of a WBEM server that serves as a general access point to a client.

It supports determining the Interop namespace of the server, all namespaces, its brand and version, the advertised management profiles and finally allows retrieving the central instances of an implementation of a management profile with one method invocation regardless of whether the profile implementation chose to implement the central or scoping class profile advertisement methodology (see section Profile advertisement methodologies).

It also provides functions to subscribe for indications.

Parameters: conn (WBEMConnection) – Connection to the WBEM server.

Attributes:

`INTEROP_NAMESPACES`	A class variable with the possible names of Interop namespaces that should be tried when determining the Interop namespace on the WBEM server.
`NAMESPACE_CLASSNAMES`	A class variable with the possible names of CIM classes for representing CIM namespaces, that should be tried when determining the namespaces on the WBEM server.
`brand`	Brand of the WBEM server.
`cimom_inst`	CIM instance of class CIM_ObjectManager that represents the WBEM server.
`conn`	Connection to the WBEM server.
`interop_ns`	Name of the Interop namespace of the WBEM server.
`namespace_classname`	Name of the CIM class that was found to represent the CIM namespaces of the WBEM server.
`namespace_paths`	Instance paths of the CIM instances in the Interop namespace that represent the namespaces of the WBEM server.
`namespaces`	Names of all namespaces of the WBEM server.
`profiles`	The CIM_RegisteredProfile instances representing all management profiles advertised by the WBEM server.
`url`	URL of the WBEM server.
`version`	Version of the WBEM server.

Methods:

`__repr__`()	Return a representation of the `WBEMServer` object with all attributes, that is suitable for debugging.
`__str__`()	Return a representation of the `WBEMServer` object with a subset of its attributes.
`create_namespace`(namespace[, verbose])	Create the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the new namespace there.
`delete_namespace`(namespace[, verbose])	Delete the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the removed namespace there.
`get_central_instances`(profile_path[, ...])	Return the instance paths of the central instances of a management profile.
`get_selected_profiles`([registered_org, ...])	Return the CIM_RegisteredProfile instances representing a filtered subset of the management profiles advertised by the WBEM server, that can be filtered by registered organization, registered name, and/or registered version.

INTEROP_NAMESPACES = ['interop', 'root/interop', 'root/PG_Interop']: A class variable with the possible names of Interop namespaces that should be tried when determining the Interop namespace on the WBEM server.

NAMESPACE_CLASSNAMES = ['CIM_Namespace', '__Namespace']: A class variable with the possible names of CIM classes for representing CIM namespaces, that should be tried when determining the namespaces on the WBEM server.

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

__str__()[source]: Return a representation of the WBEMServer object with a subset of its attributes.

property brand

Brand of the WBEM server.

The brand is determined from the CIM_ObjectManager instance in the Interop namespace, by looking at its ElementName property.

For known WBEM servers, the brand is then normalized in order to make it identifiable:

"OpenPegasus"
"SFCB" (Small Footprint CIM Broker)
"WBEM Solutions J WBEM Server"
"EMC CIM Server"
"FUJITSU CIM Object Manager"

For all other WBEM servers, the brand is the value of the ElementName property, or the string "unknown", if that property is not set or the empty string.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_NOT_FOUND, Interop namespace could not be determined. :raises CIMError: CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.

Type: string

property cimom_inst

CIM instance of class CIM_ObjectManager that represents the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_NOT_FOUND, Interop namespace could not be determined. :raises CIMError: CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.

Type: CIMInstance

property conn

Connection to the WBEM server.

Type: WBEMConnection

create_namespace(namespace, verbose=False)[source]

Create the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the new namespace there.

This method cannot create an Interop namespace because creating the an Interop namespace with client operations depends on the prior existence of an Interop namespace, and creating additional Interop namespaces if one already exists is usually prevented by servers.

This method attempts the following approaches for creating the namespace, in order, until an approach succeeds:

Namespace creation as described in the WBEM Server profile (DSP1092) via CIM method CIM_WBEMServer.CreateWBEMServerNamespace().

This is a new standard approach that is not likely to be widely implemented yet.
Issuing the CreateInstance operation using the CIM class representing namespaces (‘PG_Namespace’ for OpenPegasus, and ‘CIM_Namespace’ otherwise), against the Interop namespace.

This approach is typically supported in WBEM servers that support the creation of CIM namespaces. This approach is similar to the approach described in DSP0200.

Creating namespaces using the __Namespace pseudo-class has been deprecated already in DSP0200 1.1.0 (released in 01/2003), and pywbem does not implement that approach.

Parameters

namespace (string) – CIM namespace name. Must not be None. The namespace may contain leading and a trailing slash, both of which will be ignored.
verbose (bool) – Verbose mode: Print a message about the namespace creation.

Returns

The specified CIM namespace name in its standard format (i.e. without leading or trailing slash characters).

Return type

:raises Exceptions raised by WBEMConnection.: :raises ModelError: An error with the model implemented by the WBEM server.

delete_namespace(namespace, verbose=False)[source]

Delete the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the removed namespace there.

The specified namespace must be empty (i.e. must not contain any classes, instances, or qualifier types.

This method cannot delete the Interop namespace because servers will usually prevent their deletion.

This method attempts the following approaches for deleting the namespace, in order, until an approach succeeds:

Issuing the DeleteInstance operation using the CIM class representing namespaces (‘PG_Namespace’ for OpenPegasus, and ‘CIM_Namespace’ otherwise), against the Interop namespace.

This approach is typically supported in WBEM servers that support the creation of CIM namespaces. This approach is similar to the approach described in DSP0200.

The approach described in the WBEM Server profile (DSP1092) via deleting the CIM_WBEMServerNamespace instance is not implemented because that would also delete any classes, instances, and qualifier types in the namespace.

Deleting namespaces using the __Namespace pseudo-class has been deprecated already in DSP0200 1.1.0 (released in 01/2003), and pywbem does not implement that approach.

Parameters

namespace (string) – CIM namespace name. Must not be None. The namespace may contain leading and a trailing slash, both of which will be ignored.
verbose (bool) – Verbose mode: Print a message about the namespace creation.

Returns

The specified CIM namespace name in its standard format (i.e. without leading or trailing slash characters).

Return type

:raises Exceptions raised by WBEMConnection.: :raises ModelError: An error with the model implemented by the WBEM server. :raises CIMError: CIM_ERR_NOT_FOUND, Specified namespace does not exist. :raises CIMError: CIM_ERR_NAMESPACE_NOT_EMPTY, Specified namespace is not empty.

get_central_instances(profile_path, central_class=None, scoping_class=None, scoping_path=None, reference_direction='dmtf', try_gci_method=False)[source]

Return the instance paths of the central instances of a management profile.

DMTF defines the following profile advertisement methodologies in DSP1033:

GetCentralInstances methodology (new in DSP1033 1.1, only when explicitly requested by the caller)
Central class methodology
Scoping class methodology

A brief explanation of these methodologies can be found in section Profile advertisement methodologies.

Pywbem attempts all three profile advertisement methodologies in the order listed above.

All three methodologies start from the CIM_RegisteredProfile instance referenced by the profile_path parameter. That instance represents a management profile. In case of multiple uses of a component profile in a WBEM server, one such instance is supposed to represent one such profile use.

If the profile is a component profile and its implementation does not support the GetCentralInstances or central class methodologies, the central_class, scoping_class, and scoping_path parameters are required in order for the method to attempt the scoping class methodology. The method will not fail if these parameters are not provided, as long as the profile implementation supports the GetCentralInstances or central class methodology.

Example parameters for a 1-hop scoping path:

central_class = "CIM_Fan"
scoping_path = ["CIM_SystemDevice"]
scoping_class = "CIM_ComputerSystem"

Example parameters for a 2-hop scoping path:

central_class = "CIM_Sensor"
scoping_path = ["CIM_AssociatedSensor", "CIM_Fan", "CIM_SystemDevice"]
scoping_class = "CIM_ComputerSystem"

Parameters

profile_path (CIMInstanceName) – Instance path of the CIM_RegisteredProfile instance representing the management profile (or its use, if there are multiple uses in a WBEM server).
central_class (string) –
Class name of central class defined by the management profile.

Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
scoping_class (string) –
Class name of scoping class defined by the management profile.

Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
scoping_path (list of string) –
Scoping path defined by the management profile.

Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
reference_direction (string) –
Defines the navigation direction across the CIM_ReferencedProfile association when navigating from the current profile to its scoping (= referencing, autonomous) profile when using the scoping class methodology, as follows:
- ’dmtf’ (default): Assume DMTF conformance, i.e. the ‘Dependent’ end is followed.
- ’snia’: Assume SNIA SMI-S conformance, i.e. the ‘Antecedent’ end is followed.
This parameter supports the different definitions between DMTF and SNIA SMI-S standards regarding the use of the two ends of the CIM_ReferencedProfile association:
- The DMTF standards define in DSP1033 and DSP1001:
  - Antecedent = referenced profile = component profile
  - Dependent = referencing profile = autonomous profile
- The SNIA SMI-S standard defines in the “Profile Registration Profile” (in the SMI-S “Common Profiles” book):
  - Antecedent = autonomous profile
  - Dependent = component (= sub) profile
It should be assumed that all profiles that are directly or indirectly scoped by a particular top-level (= wrapper) specification implement the reference direction that matches the registered organisation of the top-level specification.

Examples:
- All profiles scoped by the SNIA SMI-S top-level specification should be assumed to implement the ‘snia’ reference direction.
- All profiles scoped by the DMTF SMASH wrapper specification should be assumed to implement the ‘dmtf’ reference direction.
try_gci_method (bool) – Flag indicating that the GetCentralInstances methodology should be attempted. This methodology is not expected to be implemented by WBEM servers at this point, and causes undesirable behavior with some WBEM servers, so it is not attempted by default. Note that WBEM servers are required to support the scoping class methodology.

Returns

The instance paths of the central instances of the implementation of the management profile.

Return type

list of CIMInstanceName

:raises Exceptions raised by WBEMConnection.: :raises ModelError: An error with the model implemented by the WBEM server. :raises ValueError: User errors regarding input parameter values. :raises TypeError: User errors regarding input parameter types.

get_selected_profiles(registered_org=None, registered_name=None, registered_version=None)[source]

Return the CIM_RegisteredProfile instances representing a filtered subset of the management profiles advertised by the WBEM server, that can be filtered by registered organization, registered name, and/or registered version.

Parameters

registered_org (string) – A filter for the registered organization of the profile, matching (case insensitively) the RegisteredOrganization property of the CIM_RegisteredProfile instance, via its Values qualifier. If None, this parameter is ignored for filtering.
registered_name (string) – A filter for the registered name of the profile, matching (case insensitively) the RegisteredName property of the CIM_RegisteredProfile instance. If None, this parameter is ignored for filtering.
registered_version (string) – A filter for the registered version of the profile, matching (case insensitively) the RegisteredVersion property of the CIM_RegisteredProfile instance. Note that version strings may contain aplhabetic characters to indicate the draft level. If None, this parameter is ignored for filtering.

Returns

The CIM_RegisteredProfile instances representing the filtered subset of the management profiles advertised by the WBEM server.

Return type

list of CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_NOT_FOUND, Interop namespace could not be determined. :raises ModelError: If an instance in the list of profiles is incomplete and does not include the required properties.

property interop_ns

Name of the Interop namespace of the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_NOT_FOUND, Interop namespace could not be determined.

Type: string

property namespace_classname

Name of the CIM class that was found to represent the CIM namespaces of the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises ModelError: An error with the model implemented by the WBEM server.

Type: string

property namespace_paths

Instance paths of the CIM instances in the Interop namespace that represent the namespaces of the WBEM server.

Note: One WBEM server has been found to support an Interop namespace without representing it as a CIM instance. In that case, this property will not have an instance path for the Interop namespace, but the namespaces property will have the name of the Interop namespace.

:raises Exceptions raised by WBEMConnection.: :raises ModelError: An error with the model implemented by the WBEM server.

Type: list of CIMInstanceName

property namespaces

Names of all namespaces of the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises ModelError: An error with the model implemented by the WBEM server.

Type: list of string

property profiles

The CIM_RegisteredProfile instances representing all management profiles advertised by the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_NOT_FOUND, Interop namespace could not be determined.

Type: list of CIMInstance

property url

URL of the WBEM server.

Type: string

property version

Version of the WBEM server.

None, if the version cannot be determined.

The version is determined from the CIM_ObjectManager instance in the Interop namespace, by looking at its ElementName property, or if that is not set, at its Description property, and by taking the string after "version" or "release" (case insensitively).

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_NOT_FOUND, Interop namespace could not be determined. :raises CIMError: CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.

Type: string

WBEM indication listener

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEM indication listener API supports creating and managing a thread-based WBEM listener that waits for indications (i.e. events) emitted by a WBEM server using the CIM-XML protocol. The API supports registering callback functions that get called when indications are received by the listener.

See WBEM subscription manager for the API for viewing and managing subscriptions for indications on a WBEM server.

WBEMListener

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEMListener class provides a thread-based WBEM listener service that can receive CIM indications from multiple WBEM servers and that calls registered callback functions to deliver the received indications.

Examples

The following example creates and runs a listener:

import logging
from socket import getfqdn
from pywbem import WBEMListener

def process_indication(indication, host):
    '''This function gets called when an indication is received.'''

    print("Received CIM indication from {host}: {ind!r}".
          format(host=host, ind=indication))

def main():

    # Configure logging of the listener via the Python root logger
    logging.basicConfig(
        filename='listener.log', level=logging.WARNING,
        format='%(asctime)s - %(levelname)s - %(message)s')

    certkeyfile = 'listener.pem'

    listener = WBEMListener(host=getfqdn(),
                            http_port=5990,
                            https_port=5991,
                            certfile=certkeyfile,
                            keyfile=certkeyfile)
    listener.add_callback(process_indication)

    try:
        listener.start()

        # process_indication() will be called for each received indication

        . . .  # wait for some condition to end listening

    finally:
        listener.stop()

Alternative code using the class as a context manager:

with WBEMListener(...) as listener:
    listener.add_callback(process_indication)
    listener.start()

    # process_indication() will be called for each received indication

    ... # wait for some condition to end listening

# listener.stop() has been called automatically

See the example in section WBEMSubscriptionManager for an example of using a listener in combination with a subscription manager.

Another listener example is in the script examples/listen.py (when you clone the GitHub pywbem/pywbem project). It is an interactive Python shell that creates a listener and displays any indications it receives, in MOF format.

Logging in the listener

Each WBEMListener object has its own separate Python logger object with the name:

‘pywbem.listener.{id}’

where {id} is a string that is unique for each WBEMListener object within the Python process.

The logger property of a WBEMListener object provides access to that Python logger object, if needed.

The listener will log any indications it receives and any responses it sends back to the indication sender, at the INFO logging level (see Logging Levels).

In addition, it will log errors at the ERROR logging level.

Starting with Python 2.7, the Python root logger will by default (i.e. when not being configured) print log records of logging level WARNING or greater to sys.stderr. So the indication and response interactions will not be printed by default, but any errors logged at the ERROR logging level will be printed by default.

Pywbem adds a null handler to the logger named ‘pywbem’, in order to prevent the “No handlers could be found for logger …” warning. This follows best practices recommended in Configuring logging for a library and in several articles, for example in this article. Because this warning is no longer issued on Python 3.4 and higher, pywbem adds a null handler only on Python 2.7.

WBEMListener class

class pywbem.WBEMListener(host, http_port=None, https_port=None, certfile=None, keyfile=None)[source]

New in pywbem 0.9 as experimental and finalized in 0.10.

A WBEM listener.

The listener supports starting and stopping threads that listen for CIM-XML ExportIndication messages using HTTP and/or HTTPS, and that pass any received indications on to registered callback functions.

The listener must be stopped in order to free the TCP/IP port it listens on. Using this class as a context manager ensures that the listener is stopped when leaving the context manager scope.

Parameters

host (string) – IP address or host name at which this listener can be reached.
http_port (string or integer) –
HTTP port at which this listener can be reached. Note that at least one port (HTTP or HTTPS) must be set.

None means not to set up a port for HTTP.
https_port (string or integer) –
HTTPS port at which this listener can be reached.

None means not to set up a port for HTTPS.
certfile (string) –
File path of certificate file to be used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.

It is valid for the certificate file to contain a private key; the server certificate sent during SSL/TLS handshake is sent without the private key.

None means not to use a server certificate file. Setting up a port for HTTPS requires specifying a certificate file.
keyfile (string) –
File path of private key file to be used by the server during SSL/TLS handshake when creating the secure HTTPS connection.

It is valid to specify a certificate file that contains a private key.

None means not to use a private key file. Setting up a port for HTTPS requires specifying a private key file.

Methods:

`__enter__`()	New in pywbem 0.12.
`__exit__`(exc_type, exc_value, traceback)	New in pywbem 0.12.
`__repr__`()	Return a representation of the `WBEMListener` object with all attributes, that is suitable for debugging.
`__str__`()	Return a representation of the `WBEMListener` object with a subset of its attributes.
`add_callback`(callback)	Add a callback function to the listener.
`deliver_indication`(indication, host)	This function is called by the listener threads for each received indication.
`start`()	Start the WBEM listener threads, if they are not yet running.
`stop`()	Stop the WBEM listener threads, if they are running.

Attributes:

`certfile`	File path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
`host`	IP address or host name at which this listener can be reached.
`http_port`	HTTP port at which this listener can be reached.
`http_started`	Boolean indicating whether the listener is started for the HTTP port.
`https_port`	HTTPS port at which this listener can be reached.
`https_started`	Boolean indicating whether the listener is started for the HTTPS port.
`keyfile`	File path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
`logger`	Logger object for this listener.

__enter__()[source]

New in pywbem 0.12.

Enter method when the class is used as a context manager.

Returns the listener object.

__exit__(exc_type, exc_value, traceback)[source]

New in pywbem 0.12.

Exit method when the class is used as a context manager.

Stops the listener by calling stop().

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

__str__()[source]: Return a representation of the WBEMListener object with a subset of its attributes.

add_callback(callback)[source]

Add a callback function to the listener.

The callback function will be called for each indication this listener receives from any WBEM server.

If the callback function is already known to the listener, it will not be added.

Parameters: callback (callback_interface()) – Callable that is being called for each CIM indication that is received while the listener threads are running.

property certfile

File path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.

None means there is no certificate file being used (that is, no port is set up for HTTPS).

Type: string

deliver_indication(indication, host)[source]

This function is called by the listener threads for each received indication. It is not supposed to be called by the user.

It delivers the indication to all callback functions that have been added to the listener.

If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.

Parameters

indication (CIMInstance) – Representation of the CIM indication to be delivered.
host (string) – Host name or IP address of WBEM server sending the indication.

property host

IP address or host name at which this listener can be reached.

Type: string

property http_port

HTTP port at which this listener can be reached.

None means there is no port set up for HTTP.

Type: integer

property http_started

Boolean indicating whether the listener is started for the HTTP port.

If no port is set up for HTTP, False is returned.

New in pywbem 0.12.

Type: bool

property https_port

HTTPS port at which this listener can be reached.

None means there is no port set up for HTTPS.

Type: integer

property https_started

Boolean indicating whether the listener is started for the HTTPS port.

If no port is set up for HTTPS, False is returned.

New in pywbem 0.12.

Type: bool

property keyfile

File path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection.

None means there is no certificate file being used (that is, no port is set up for HTTPS).

Type: string

property logger

Logger object for this listener.

Each listener object has its own separate logger object with the name:

‘pywbem.listener.{id}’

where {id} is a unique string for each listener object.

Users of the listener should not look up the logger object by name, but should use this property to get to it.

Type: logging.Logger

start()[source]

Start the WBEM listener threads, if they are not yet running.

A thread serving CIM-XML over HTTP is started if an HTTP port was specified for the listener. A thread serving CIM-XML over HTTPS is started if an HTTPS port was specified for the listener.

These server threads will handle the ExportIndication export message described in DSP0200 and they will invoke the registered callback functions for any received CIM indications.

The listener must be stopped again in order to free the TCP/IP port it listens on. The listener can be stopped explicitly using the stop() method. The listener will be automatically stopped when the main thread terminates (i.e. when the Python process terminates), or when WBEMListener is used as a context manager when leaving its scope.

In case of HTTPS, the private key file and certificate file are used. If the private key file is protected with a password, the password will be prompted for using getpass.getpass(). If the password is invalid, or if the private key file or certificate file are invalid, pywbem.ListenerCertificateError is raised.

Raises

pywbem.ListenerCertificateError – Error with the certificate file or its private key file when using HTTPS.
pywbem.ListenerPortError – WBEM listener port is already in use.
pywbem.ListenerPromptError – Error when prompting for the password of the private key file when using HTTPS.
OSError – Other error
IOError – Other error (Python 2.7 only)

stop()[source]: Stop the WBEM listener threads, if they are running.

pywbem.callback_interface(indication, host)[source]

New in pywbem 0.9 as experimental and finalized in 0.10.

Interface of a callback function that is provided by the user of the API and that will be called by the listener for each received CIM indication.

Parameters

indication (CIMInstance) – Representation of the CIM indication that has been received. Its path attribute is None.
host (string) – Host name or IP address of WBEM server sending the indication.

Raises

Exception – If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.

Listener exceptions

class pywbem.ListenerCertificateError(message)[source]

This exception indicates an error with the certificate file or its private key file when using HTTPS.

New in pywbem 1.3.

Derived from ListenerError.

This includes bad format of the files, file not found, permission errors when accessing the files, or an invalid password for the private key file.

Parameters: message (string) – Error message (will be put into args[0]).
Variables: args – A tuple (message, ) set from the corresponding init argument.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.ListenerPortError(message)[source]

This exception indicates that the port for the pywbem listener is already in use.

New in pywbem 1.3.

Derived from ListenerError.

Parameters: message (string) – Error message (will be put into args[0]).
Variables: args – A tuple (message, ) set from the corresponding init argument.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.ListenerPromptError(message)[source]

This exception indicates that the prompt for the password of the private key file of the pywbem listener was interrupted or ended.

New in pywbem 1.3.

Derived from ListenerError.

Parameters: message (string) – Error message (will be put into args[0]).
Variables: args – A tuple (message, ) set from the corresponding init argument.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.ListenerError(message)[source]

Abstract base class for exceptions raised by the pywbem listener (i.e. class WBEMListener).

New in pywbem 1.3.

Derived from Exception.

Parameters: message (string) – Error message (will be put into args[0]).
Variables: args – A tuple (message, ) set from the corresponding init argument.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

WBEM subscription manager

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEM subscription manager API supports viewing and managing subscriptions for indications on a WBEM server.

See WBEM indication listener for the API for creating and managing a WBEM listener.

WBEMSubscriptionManager

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEMSubscriptionManager class is a subscription manager that provides for creating and removing indication subscriptions (including indication filters and listener destinations) for multiple WBEM servers and multiple WBEM listeners and for getting information about existing indication subscriptions.

The SubscriptionManager only manages CIM/XML listener destinations and does not view, add, or remove other destinations such as files, etc.

The CIM/XML WBEM listener is identified through its URL, so it may be the pywbem listener (that is, a WBEMListener object) or any other WBEM listener.

This subscription manager supports three types of ownership of the CIM instances in WBEM servers that represent subscriptions, filters and listener destinations:

Owned

Owned CIM instances are created via the subscription manager and their life cycle is bound to the life cycle of the registration of that WBEM server with the subscription manager via add_server().

Owned CIM instances are deleted automatically when their WBEM server is deregistered from the subscription manager via remove_server() or remove_all_servers(). In addition, they can be deleted by the user via the removal methods of the WBEMSubscriptionManager class.
Permanent

Permanent CIM instances are created via the subscription manager and their life cycle is independent of the life cycle of the registration of that WBEM server with the subscription manager.

Permanent CIM instances are not deleted automatically when their WBEM server is deregistered from the subscription manager. The user is responsible for their lifetime management: They can be deleted via the removal methods of the WBEMSubscriptionManager class.
Static

Static CIM instances pre-exist in the WBEM server and cannot be deleted (or created) by a WBEM client.

If a client creates a subscription between a filter and a listener destination, the types of ownership of these three CIM instances may be arbitrarily mixed, with one exception:

A permanent subscription cannot be created on an owned filter or an owned listener destination. Allowing that would prevent the automatic life cycle management of the owned filter or listener destination by the subscription manager. This restriction is enforced by the WBEMSubscriptionManager class.

The WBEMSubscriptionManager object remembers owned subscriptions, filters, and listener destinations. If for some reason that object gets deleted before all servers could be removed (e.g. because the Python program aborts or the client is terminated), the corresponding CIM instances in the WBEM server still exist, but the knowledge is lost that these instances were owned by that subscription manager. Therefore, the subscription manager discovers owned subscriptions, filters, and listener destinations when a server is added. For this discovery, is based upon the Name property. Therefore, if the Name property is set by the user (e.g. because a management profile requires a particular name), the filter must be permanent and cannot be owned.

Since WBEMSubscriptionManager does not directly modify existing instances of filter or destinations or subscriptions, the user must do this directly through the ModifyInstance WBEM request method and then update the local owned instances list by executing get_all_filters(), get_all_destinations(), or get_all_subscriptions().

Examples

The following example code demonstrates the use of a subscri tion manager to subscribe for a CIM alert indication on a WBEM server. The WBEM listener is assumed to exist somewhere and is identified by its URL:

from pywbem import WBEMConnection, WBEMServer, WBEMSubscriptionManager

server_url = 'http://myserver'
server_credentials = ('myuser', 'mypassword')

listener_url = 'http://mylistener'

conn = WBEMConnection(server_url, server_credentials)
server = WBEMServer(conn)
sub_mgr = WBEMSubscriptionManager(subscription_manager_id='fred')

# Register the server in the subscription manager:
server_id = sub_mgr.add_server(server)

# Add a listener destination in the server:
dest_inst = sub_mgr.add_destination(
    server_id, listener_url, owned=True, destination_id='id1')

# Subscribe to a static filter of a given name:
filter1_name = "DMTF:Indications:GlobalAlertIndicationFilter"
filter1_insts = sub_mgr.get_all_filters(server_id)
for inst in filter1_insts:
    if inst['Name'] == filter1_name:
        sub_mgr.add_subscriptions(server_id, inst.path, dest_inst.path)
        break

# Create a dynamic alert filter and subscribe to it:
filter2_source_ns = "root/cimv2"
filter2_query = "SELECT * FROM CIM_AlertIndication " \
                "WHERE OwningEntity = 'DMTF' " \
                "AND MessageID LIKE 'SVPC0123|SVPC0124|SVPC0125'"
filter2_language = "DMTF:CQL"
filter2_inst = sub_mgr.add_filter(
    server_id, filter2_source_ns, filter2_query, filter2_language,
    owned=True, filter_id="myalert")
sub_mgr.add_subscriptions(server_id, filter2_inst.path, dest_inst.path)

The following example code briefly shows how to use a subscription manager as a context manager, in order to get automatic cleanup of owned instances:

with WBEMSubscriptionManager('fred') as sub_mgr:
    server_id = sub_mgr.add_server(server)
    . . .
# The exit method automatically calls remove_all_servers(), which deletes
# all owned subscription, filter and destination instances in the servers
# that were registered.

The Tutorial section contains a tutorial about the subscription manager.

class pywbem.WBEMSubscriptionManager(subscription_manager_id)[source]

New in pywbem 0.9 as experimental and finalized in 0.10.

A class for managing subscriptions for CIM indications in a WBEM server.

The class may be used as a Python context manager, in order to get automatic clean up (see __exit__()).

Parameters

subscription_manager_id (string) –

A subscription manager ID string that is used as a component in the value of the Name property of indication filter and listener destination instances and thus allows identifying these instances in a WBEM server.

Must not be None.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

Raises

ValueError – Incorrect input parameter values.
TypeError – Incorrect input parameter types.

Methods:

`__enter__`()	New in pywbem 0.10.
`__exit__`(exc_type, exc_value, traceback)	New in pywbem 0.10.
`__repr__`()	Return a representation of the `WBEMSubscriptionManager` object with all attributes, that is suitable for debugging.
`__str__`()	Return a representation of the `WBEMSubscriptionManager` object with a subset of its attributes.
`add_destination`(server_id, listener_url[, ...])	Add a listener destination to be the target of indications sent by a WBEM server, by creating an instance of CIM class "CIM_ListenerDestinationCIMXML" in the Interop namespace of the server.
`add_filter`(server_id, source_namespaces, query)	Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class "CIM_IndicationFilter") in the Interop namespace of the server.
`add_server`(server)	Register a WBEM server with the subscription manager.
`add_subscriptions`(server_id, filter_path[, ...])	Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destinations, by creating indication subscription instances (of CIM class "CIM_IndicationSubscription") in the Interop namespace of that server.
`get_all_destinations`(server_id)	Return all listener destinations in a WBEM server.
`get_all_filters`(server_id)	Return all indication filters in a WBEM server.
`get_all_subscriptions`(server_id)	Return all indication subscriptions in a WBEM server.
`get_owned_destinations`(server_id)	Return the listener destinations in a WBEM server owned by this subscription manager.
`get_owned_filters`(server_id)	Return the indication filters in a WBEM server owned by this subscription manager.
`get_owned_subscriptions`(server_id)	Return the indication subscriptions in a WBEM server owned by this subscription manager.
`remove_all_servers`()	Remove all registered WBEM servers from the subscription manager.
`remove_destinations`(server_id, destination_paths)	Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.
`remove_filter`(server_id, filter_path)	Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server.
`remove_server`(server_id)	Remove a registered WBEM server from the subscription manager.
`remove_subscriptions`(server_id, sub_paths)	Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.

__enter__()[source]

New in pywbem 0.10.

Enter method when the class is used as a context manager. Returns the subscription manager object

__exit__(exc_type, exc_value, traceback)[source]

New in pywbem 0.10.

Exit method when the class is used as a context manager.

It cleans up by calling remove_all_servers().

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

__str__()[source]: Return a representation of the WBEMSubscriptionManager object with a subset of its attributes.

add_destination(server_id, listener_url, owned=True, destination_id=None, name=None, persistence_type=None)[source]

Add a listener destination to be the target of indications sent by a WBEM server, by creating an instance of CIM class “CIM_ListenerDestinationCIMXML” in the Interop namespace of the server.

The Name property of the created listener destination instance can be set in one of two ways:

directly by specifying the name parameter.

In this case, the Name property is set directly to the name parameter.

This should be used in cases where the user needs to have control over the destination name (e.g. because a DMTF management profile requires a particular name).

The name parameter can only be specified for permanent destinations.
indirectly by specifying the destination_id parameter.

In this case, the value of the Name property will be:

"pywbemdestination:" {submgr_id} ":" {destination_id}

where:
- {submgr_id} is the subscription manager ID
- {destination_id} is the value of the destination_id parameter
The destination_id parameter can only be specified for owned destinations.

If an owned listener destination instance for the specified listener URL and PersistenceType already exists, it is returned without creating a new instance.

If a listener destination instance with the specified or generated Name property already exists, the method raises CIMError(CIM_ERR_ALREADY_EXISTS). Note that this is a more strict behavior than what a WBEM server would do, because the Name property is only one of four key properties.

Parameters

server_id (string) – The server ID of the WBEM server, returned by add_server().
listener_url (string) –
The URL of the WBEM listener that should receive the indications.

The WBEM listener may be a WBEMListener object or any external WBEM listener.

The listener URL string must have the format:

[{scheme}://]{host}:{port}

The following URL schemes are supported:
- https: Causes HTTPS to be used.
- http: Causes HTTP to be used. This is the default
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986 with the extensions for zone identifiers as defined in RFC6874, supporting - (minus) for the delimiter before the zone ID string, as an additional choice to %25.
The port is required in the listener URL.

See WBEMConnection for examples of valid URLs, with the caveat that the port in server URLs is optional.
owned (bool) – Defines the ownership type of the created listener destination instance: If True, it will be owned. Otherwise, it will be permanent. See WBEMSubscriptionManager for details about these ownership types.
destination_id (string) –
A destination ID string that is used as a component in the value of the Name property of owned destination instances to help the user identify these instances in a WBEM server, or None if the name parameter is specified.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

This parameter is required for owned destinations and is rejected for permanent destinations.
name (string) –
The destination name to be used directly for the Name property of permanent destination instances, or None if the destination_id parameter is specified.

This parameter is required for permanent destinations and is rejected for owned destinations.
persistence_type (string) –
Optional string where the allowed strings are “transient” and “permanent” and the default is None. The strings are used to set the PersistenceType property, an integer property with the values of 2 (Permanent) or 3 (Transient)

The default value is None so that the PersistenceType property is not created on the destination instance for permanent filters. and is created with PersistenceType 3 (Transient) for owned destinations.

Most WBEM servers set the PersistenceType value to 2 (Permanent) if no value is provided.

This method does not provide for adding the OtherPersistenceType property.

Returns

The created listener destination instance for the defined listener URL.

Return type

CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises CIMError(CIM_ERR_ALREADY_EXISTS): A filter with the specified or generated Name property already exists in the server. :raises ValueError: Incorrect input parameter values.

add_filter(server_id, source_namespaces, query, query_language='WQL', owned=True, filter_id=None, name=None, source_namespace=None)[source]

Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class “CIM_IndicationFilter”) in the Interop namespace of the server.

The Name property of the created filter instance can be set in one of two ways:

directly by specifying the name parameter.

In this case, the Name property is set directly to the name parameter.

This should be used in cases where the user needs to have control over the filter name (e.g. because a DMTF management profile requires a particular name).

The name parameter can only be specified for permanent filters.
indirectly by specifying the filter_id parameter.

In this case, the value of the Name property will be:

"pywbemfilter:" {submgr_id} ":" {filter_id}

where:
- {submgr_id} is the subscription manager ID
- {filter_id} is the filter ID
The filter_id parameter can only be specified for owned filters.

If an indication filter instance with the specified or generated Name property already exists, the method raises CIMError(CIM_ERR_ALREADY_EXISTS). Note that this is a more strict behavior than what a WBEM server would do, because the Name property is only one of four key properties.

Parameters

server_id (string) – The server ID of the WBEM server, returned by add_server().
source_namespaces (string, list of string, or None) – Source namespace or list of source namespaces of the indication filter. The values will be inserted into the CIM_IndicationFilter SourceNamespaces property. If None, the SourceNamespaces property will not be created. and the WBEM server will use the Interop namespace as the source namespace for the indication filter.
query (string) – Filter query in the specified query language.
query_language (string) –
Query language for the specified filter query.

Examples: ‘WQL’, ‘DMTF:CQL’.
owned (bool) – Defines the ownership type of the created indication filter instance: If True, it will be owned. Otherwise, it will be permanent. See WBEMSubscriptionManager for details about these ownership types.
filter_id (string) –
A filter ID string that is used as a component in the value of the Name property of filter instances to help the user identify these instances in a WBEM server, or None if the name parameter is specified.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

This parameter is required for owned filters and is rejected for permanent filters.

There is no requirement that the filter ID be unique. This can be used to identify groups of filters by using the same value for multiple filters.
name (string) –
New in pywbem 0.10.

The filter name to be used directly for the Name property of the filter instance, or None if the filter_id parameter is specified.

This parameter is required for permanent filters and is rejected for owned filters.
source_namespace (string) – Optional source namespace of the indication filter. If the parameter is provided the value will be inserted into the CIM_IndicationFilter SourceNamespace property. Otherwise the SourceNamespace property will not be created. The SourceNamespace property is deprecated in the DMTF CIM_IndicationFilter class in favor of SourceNamespaces (see the SourceNamespaces parameter above). This parameter is provided only to support calls to add_filter() that use the source_namespace as a keyword parameter or to support very old WBEM servers (prior to DMTF schema version 2.22) that require the SourceNamespace property.

Returns

The created indication filter instance.

Return type

CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises CIMError(CIM_ERR_ALREADY_EXISTS): A filter with the specified or generated Name property already exists in the server. :raises ValueError: Incorrect input parameter values. :raises TypeError: Incorrect input parameter types.

add_server(server)[source]

Register a WBEM server with the subscription manager. This is a prerequisite for adding listener destinations, indication filters and indication subscriptions to the server.

This method discovers listener destination, indication filter, and subscription instances in the WBEM server owned by this subscription manager, and registers them in the subscription manager as if they had been created through it.

In this discovery process, listener destination and indication filter instances are matched based upon the value of their Name property. Subscription instances are matched based upon the ownership of the referenced destination and filter instances: If a subscription references a filter or a destination that is owned by this subscription manager, it is considered owned by this subscription manager as well.

Parameters: server (WBEMServer) – The WBEM server.
Returns: An ID for the WBEM server, for use by other methods of this class.
Return type: string

:raises Exceptions raised by WBEMConnection.: :raises ValueError: Incorrect input parameter values. :raises TypeError: Incorrect input parameter types.

add_subscriptions(server_id, filter_path, destination_paths=None, owned=True)[source]

Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destinations, by creating indication subscription instances (of CIM class “CIM_IndicationSubscription”) in the Interop namespace of that server.

The specified indication filter may be owned, permanent or static.

The specified listener destinations may be owned, permanent or static.

When creating permanent subscriptions, the indication filter and the listener destinations must not be owned.

Owned subscriptions are added conditionally: If the subscription instance to be added is already registered with this subscription manager and has the same path, it is not created or modified. In that case, the instance already registered is returned. This method does not modify subscriptions.

Permanent subscriptions are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.

Upon successful return of this method, the added subscriptions are active, so that the specified WBEM listeners may immediately receive indications.

Parameters

server_id (string) – The server ID of the WBEM server, returned by add_server().
filter_path (CIMInstanceName) – Instance path of the indication filter instance in the WBEM server that specifies the indications to be sent.
destination_paths (CIMInstanceName or list of CIMInstanceName) –
Instance paths of the listener destination instances in the WBEM server that specify the target WBEM listener.

If None, subscriptions will be created for all owned listener destinations registered to this subscription manager.
owned (bool) – Defines the ownership type of the created subscription instances: If True, they will be owned. Otherwise, they will be permanent. See WBEMSubscriptionManager for details about these ownership types.

Returns

The indication subscription instances created in the WBEM server or the instance already in the WBEM server if the new instance is owned and there is already an owned subscription with the same path.

Return type

list of CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises ValueError: Incorrect input parameter values.

get_all_destinations(server_id)[source]

Return all listener destinations in a WBEM server.

This function contacts the WBEM server and retrieves the listener destinations by enumerating the instances of CIM class “CIM_ListenerDestinationCIMXML” in the Interop namespace of the WBEM server.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns: The listener destination instances.
Return type: list of CIMInstance

:raises Exceptions raised by WBEMConnection.:

get_all_filters(server_id)[source]

Return all indication filters in a WBEM server.

This function contacts the WBEM server and retrieves the indication filters by enumerating the instances of CIM class “CIM_IndicationFilter” in the Interop namespace of the WBEM server.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns: The indication filter instances.
Return type: list of CIMInstance

:raises Exceptions raised by WBEMConnection.:

get_all_subscriptions(server_id)[source]

Return all indication subscriptions in a WBEM server.

This function contacts the WBEM server and retrieves the indication subscriptions by enumerating the instances of CIM class “CIM_IndicationSubscription” in the Interop namespace of the WBEM server.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns: The indication subscription instances.
Return type: list of CIMInstance

:raises Exceptions raised by WBEMConnection.:

get_owned_destinations(server_id)[source]

Return the listener destinations in a WBEM server owned by this subscription manager.

This function accesses only the local list of owned destinations; it does not contact the WBEM server. The local list of owned destinations is discovered from the WBEM server when the server is registered with the subscription manager, and is maintained from then on as changes happen through this subscription manager.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns: The listener destination instances.
Return type: list of CIMInstance

get_owned_filters(server_id)[source]

Return the indication filters in a WBEM server owned by this subscription manager.

This function accesses only the local list of owned filters; it does not contact the WBEM server. The local list of owned filters is discovered from the WBEM server when the server is registered with the the subscription manager, and is maintained from then on as changes happen through this subscription manager.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns: The indication filter instances.
Return type: list of CIMInstance

get_owned_subscriptions(server_id)[source]

Return the indication subscriptions in a WBEM server owned by this subscription manager.

This function accesses only the local list of owned subscriptions; it does not contact the WBEM server. The local list of owned subscriptions is discovered from the WBEM server when the server is registered with the subscription manager, and is maintained from then on as changes happen through this subscription manager.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns: The indication subscription instances.
Return type: list of CIMInstance

remove_all_servers()[source]

Remove all registered WBEM servers from the subscription manager. This also unregisters listeners from these servers and removes all owned indication subscriptions, owned indication filters, and owned listener destinations.

:raises Exceptions raised by WBEMConnection.:

remove_destinations(server_id, destination_paths)[source]

Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.

The listener destinations must be owned or permanent (i.e. not static).

This method verifies that there are not currently any subscriptions on the listener destinations to be removed, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.

Parameters

server_id (string) – The server ID of the WBEM server, returned by add_server().
destination_paths (CIMInstanceName or list of CIMInstanceName) – Instance path(s) of the listener destination instance(s) in the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_FAILED, if there are referencing subscriptions.

remove_filter(server_id, filter_path)[source]

Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server.

The indication filter must be owned or permanent (i.e. not static).

This method verifies that there are not currently any subscriptions on the specified indication filter, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.

Parameters

server_id (string) – The server ID of the WBEM server, returned by add_server().
filter_path (CIMInstanceName) – Instance path of the indication filter instance in the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_FAILED, if there are referencing subscriptions.

remove_server(server_id)[source]

Remove a registered WBEM server from the subscription manager. This also unregisters listeners from that server and removes all owned indication subscriptions, owned indication filters and owned listener destinations.

Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server().

:raises Exceptions raised by WBEMConnection.:

remove_subscriptions(server_id, sub_paths)[source]

Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.

The indication subscriptions must be owned or permanent (i.e. not static).

Parameters

server_id (string) – The server ID of the WBEM server, returned by add_server().
sub_paths (CIMInstanceName or list of CIMInstanceName) – Instance path(s) of the indication subscription instance(s) in the WBEM server.

:raises Exceptions raised by WBEMConnection.:

MOF compiler

The language in which CIM classes, CIM Instances, etc. are specified, is called MOF (for Managed Object Format). It is defined in DSP0004.

MOF compilers take MOF files as input, compile them and use the result (CIM classes, instances, and/or qualifier declarations) to update a target CIM repository. The repository may initially be empty, or may contain CIM classes, instances, and/or qualifier declarations that are used to resolve dependencies the new MOF compilation may have.

The pywbem package includes a MOF compiler that is provided in two forms:

as an API (described in this chapter)
as a command (described in section mof_compiler)

The pywbem MOF compiler will compile MOF files whose syntax complies with DSP0004, with some limitations:

Although there is no formal keyword list of illegal words for property/parameter.etc. names , there is a list of mof syntax tokens in DSP0004 section A.3. Generally these should not be used as property names. The pywbem MOF compiler largely enforces this so that words like ‘indication’ are not allowed as property/parameter/etc. names.
The key properties of instances with aliases must be initialized in the instance specification, or their default values must be non-NULL. (See pywbem issue #1079).
An alias must be defined before it is used. In DSP0004, no such requirement is documented. (See pywbem issue #1079).
The namespace pragma only accepts CIM namespace name and not full CIM namespace path as defined in DSP0004. If the host component is part of the namespace name in a namespace pragma, the compiler generates an exception.

The MOF compiler API provides for invoking the MOF compiler programmatically. It consists of the following parts, which are described in the remaining sections of this chapter:

MOFCompiler Class - Describes the MOFCompiler class, which allows invoking the MOF compiler programmatically.
Repository connections - Describes the BaseRepositoryConnection class that defines the interface for connecting to a CIM repository. This is an extension point where users can implement a CIM repository for use by the MOF compiler.
Exceptions - Describes the exceptions that can be raised by the MOF compiler API.

MOFCompiler Class

class pywbem.MOFCompiler(handle, search_paths=None, verbose=False, log_func=<function _print_logger>)[source]

A MOF compiler. See MOF compiler for an explanation of MOF compilers in general.

A MOF compiler may be associated with one CIM repository. The repository is used for looking up dependent CIM elements (e.g. the superclass specified in a class whose MOF definition is being compiled), and it is also updated with the result of the compilation. A repository contains CIM namespaces, and the namespaces contain CIM classes, instances and qualifier types.

The association of a MOF compiler with a CIM repository is established when creating an object of this class. The interactions with the CIM repository are defined in the abstract base class BaseRepositoryConnection.

Parameters

handle (BaseRepositoryConnection or WBEMConnection) –
A handle identifying the CIM repository that will be associated with the MOF compiler.

If the provided object is a repository connection (i.e. derived from BaseRepositoryConnection, typically that would be a MOFWBEMConnection object), it is directly used by the MOF compiler to interface with the repository.

If the provided object is a WBEM connection (i.e. WBEMConnection or FakedWBEMConnection), the MOF compiler connects directly to interface defined by handle.

None means that no CIM repository will be associated. In this case, the MOF compiler can only process standalone MOF that does not depend on existing CIM elements in the repository.
search_paths (iterable of string or string) –
Directory path name(s) where the MOF compiler will search for MOF dependent files if the MOF element they define is not in the target namespace of the CIM repository. The compiler searches the specified directories and their subdirectories.

MOF dependent files are:
- The MOF file defining the superclass of a class that is compiled. The MOF file searched for is ‘<classname>.mof’.
- The MOF file defining the qualifier type of a qualifier that is specified on a MOF element that is compiled. The MOF files searched for are ‘qualifiers.mof’ and ‘qualifiers_optional.mof’.
- The MOF file of a class specified in a reference property or in the EmbeddedInstance qualifier that is compiled. The MOF file searched for is ‘<classname>.mof’. This is only partly implemented, see issue #1138.
Note that MOF include files are not searched for; they are specified in the pragma include directive as a file path relative to the including file.
verbose (bool) – Indicates whether to issue more detailed compiler messages.
log_func (callable) – A logger function that is invoked for each compiler message. The logger function must take one parameter of string type (byte string or unicode string). The default logger function prints to stdout. If None, compiler messages are not logged.

Methods:

`compile_embedded_value`(mof, ns[, filename])	Compile a string of MOF statements that must represent one or CIMInstance objects and save the resulting CIMInstance(s) in a known variable.
`compile_file`(filename, ns)	Compile a MOF file into a namespace of the associated CIM repository.
`compile_string`(mof, ns[, filename])	Compile a string of MOF statements into a namespace of the associated CIM repository.
`conn_close`()	Close the underlying connection, if it is a WBEMConnection.
`find_mof`(classname)	Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler.
`rollback`([verbose])	Rollback any changes to the CIM repository that were performed by compilations using this MOF compiler object, since the object was created.

compile_embedded_value(mof, ns, filename=None)[source]

Compile a string of MOF statements that must represent one or CIMInstance objects and save the resulting CIMInstance(s) in a known variable. Thiis method in conjunction with the compiler does not put the compiled instances into the repository but returns them to the user.

Parameters

mof (string or list of string) – The string or list of strings MOF statements to be compiled.
ns (string) – The name of the CIM namespace in the associated CIM repository that is used for lookup of any dependent CIM elements, and that is also the target of the compilation. If None, the default namespace of the connection is used. The namespace specified in this parameter must exist.
filename (string) – The path name of the file that the MOF statements were read from. This information is used only in compiler messages.

Raises

MOFCompileError – Error compiling the MOF.

compile_file(filename, ns)[source]

Compile a MOF file into a namespace of the associated CIM repository.

Parameters

filename (string) – The path name of the MOF file containing the MOF statements to be compiled.
ns (string) – The name of the CIM namespace in the associated CIM repository that is the target of the compilation, and is also used for lookup of any dependent CIM elements. If None, the default namespace of the connection is used. A namespace defined in a namespace pragma of the MOF superceeds this namespace from the point in the compilation unit(string/file) where it is declared. The namespace specified in this parameter or the MOF inamespace pragma must exist.

Raises

IOError – MOF file not found.
MOFCompileError – Error compiling the MOF.

compile_string(mof, ns, filename=None)[source]

Compile a string of MOF statements into a namespace of the associated CIM repository.

Parameters

mof (string) – The string of MOF statements to be compiled.
ns (string) – The name of the CIM namespace in the associated CIM repository that is the target of the compilation, and is also used for lookup of any dependent CIM elements. If None, the default namespace of the connection is used. A namespace defined in a MOF ‘#pragma namespace’ directive supersedes this namespace from the point in the compilation unit(string/file) where it is declared. The namespace specified in this parameter or in the MOF ‘#pragma namespace’ directive must exist.
filename (string) – The path name of the file that the MOF statements were read from. This information is used only in compiler messages.

Raises

MOFCompileError – Error compiling the MOF.

conn_close()[source]: Close the underlying connection, if it is a WBEMConnection.

find_mof(classname)[source]

Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler.

The MOF file is found based on its file name: It is assumed that the base part of the file name is the CIM class name.

Example: The class “CIM_ComputerSystem” is expected to be in a file “CIM_ComputerSystem.mof”.

Parameters: classame (string) – The name of the CIM class to look up.
Returns: Path name of the MOF file defining the CIM class, if it was found. None, if it was not found.
Return type: string

rollback(verbose=False)[source]: Rollback any changes to the CIM repository that were performed by compilations using this MOF compiler object, since the object was created.

Repository connections

class pywbem.BaseRepositoryConnection[source]

An abstract base class for implementing CIM repository connections (or an entire CIM repository) for use by the MOF compiler. This class defines the interface that is used by the MOFCompiler class when it interacts with its associated CIM repository.

Class MOFCompiler invokes only the WBEM operations that are defined as methods on this class:

EnumerateInstanceNames() - Enumerate the paths of CIM instances in the repository.
CreateInstance() - Create a CIM instance in the repository.
ModifyInstance() - Modify a CIM instance in the repository.
DeleteInstance() - Delete a CIM instance in the repository.
GetClass() - Retrieve a CIM class from the repository.
ModifyClass() - Modify a CIM class in the repository.
CreateClass() - Create a CIM class in the repository.
DeleteClass() - Delete a CIM class in the repository.
EnumerateQualifiers() - Enumerate CIM qualifier types in the repository.
GetQualifier() - Retrieve a CIM qualifier type from the repository.
SetQualifier() - Create or modify a CIM qualifier type in the repository.
DeleteQualifier() - Delete a qualifier type from the repository.

Raises: Implementation classes should raise only exceptions derived from Error or use assert for methods that are not implemented. Other exceptions are considered programming errors.

Methods:

`CreateClass`(args, *kwargs)	Create a CIM class in a namespace of the CIM repository.
`CreateInstance`(args, *kwargs)	Create a CIM instance in a namespace of the CIM repository.
`DeleteClass`(args, *kwargs)	Delete a CIM class in a namespace of the CIM repository.
`DeleteInstance`(args, *kwargs)	Delete a CIM instance in a namespace of the CIM repository.
`DeleteQualifier`(args, *kwargs)	Delete a CIM qualifier type in a namespace of the CIM repository.
`EnumerateInstanceNames`(args, *kwargs)	Enumerate the instance paths of CIM instances in a namespace of the CIM repository.
`EnumerateQualifiers`(args, *kwargs)	Enumerate the CIM qualifier types in a namespace of the CIM repository.
`GetClass`(args, *kwargs)	Retrieve a CIM class in a namespace of the CIM repository.
`GetQualifier`(args, *kwargs)	Retrieve a CIM qualifier type in a namespace of the CIM repository.
`ModifyClass`(args, *kwargs)	Modify a CIM class in a namespace of the CIM repository.
`ModifyInstance`(args, *kwargs)	Modify a CIM instance in a namespace of the CIM repository.
`SetQualifier`(args, *kwargs)	Create or modify a CIM qualifier type in a namespace of the CIM repository.

Attributes:

default_namespace

The default repository namespace.

abstract CreateClass(*args, **kwargs)[source]

Create a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateClass().

abstract CreateInstance(*args, **kwargs)[source]

Create a CIM instance in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateInstance().

abstract DeleteClass(*args, **kwargs)[source]

Delete a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteClass().

abstract DeleteInstance(*args, **kwargs)[source]

Delete a CIM instance in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteInstance().

abstract DeleteQualifier(*args, **kwargs)[source]

Delete a CIM qualifier type in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteQualifier().

abstract EnumerateInstanceNames(*args, **kwargs)[source]

Enumerate the instance paths of CIM instances in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateInstanceNames().

abstract EnumerateQualifiers(*args, **kwargs)[source]

Enumerate the CIM qualifier types in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateQualifiers().

abstract GetClass(*args, **kwargs)[source]

Retrieve a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.GetClass().

abstract GetQualifier(*args, **kwargs)[source]

Retrieve a CIM qualifier type in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.GetQualifier().

abstract ModifyClass(*args, **kwargs)[source]

Modify a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.ModifyClass().

abstract ModifyInstance(*args, **kwargs)[source]

Modify a CIM instance in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.ModifyInstance().

abstract SetQualifier(*args, **kwargs)[source]

Create or modify a CIM qualifier type in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.SetQualifier().

property default_namespace

The default repository namespace.

This property is settable.

Type: string

class pywbem.MOFWBEMConnection(conn=None)[source]

A CIM repository connection to an in-memory repository on top of an optional underlying WBEM connection.

If a WBEM connection is provided with the conn parameter, that connection is the target for any operations that acquire CIM objects and the in-memory store acts as a cache for CIM qualifiers declarations, CIM Classes, and CIM Instances created and as a rollback log in support of rolling back the operations. This is the mode in which the MOF compiler uses this class.

If the underlying WBEM connection is not provided, the in-memory repository acts as a CIM repository that is targeted by the operations. This mode is used for testing only.

MOFWBEMConnection only implements the BaseRepositoryConnection methods required to implement the mof compiler rollback functionality.

This class implements the BaseRepositoryConnection interface.

This implementation sets the path component of instances created including keybindings using property values in the instance. It does NOT confirm that all key properties are included in the path.

Raises

The methods of this class may raise any exceptions described for class WBEMConnection.

Parameters

conn (BaseRepositoryConnection) –

The underlying repository connection.

None means that there is no underlying repository and all operations performed through this object will fail.

Methods:

`CreateClass`(args, *kwargs)	Create a CIM class in the local repository of this class.
`CreateInstance`(args, *kwargs)	Create a CIM instance in the local repository of this class.
`DeleteClass`(args, *kwargs)	This method is only invoked by `rollback()` (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
`DeleteInstance`(args, *kwargs)	This method is only invoked by `rollback()` (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
`DeleteQualifier`(args, *kwargs)	This method is only invoked by `rollback()` (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
`EnumerateInstanceNames`(args, *kwargs)	This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND.
`EnumerateQualifiers`(args, *kwargs)	Enumerate the qualifier types in the local repository of this class.
`GetClass`(args, *kwargs)	Retrieve a CIM class from the local repository of this class.
`GetQualifier`(args, *kwargs)	Retrieve a qualifier type from the local repository of this class.
`ModifyClass`(args, *kwargs)	This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class.
`ModifyInstance`(args, *kwargs)	This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance.
`SetQualifier`(args, *kwargs)	Create or modify a qualifier type in the local repository of this class.
`getns`()	string: Return the default repository namespace to be used.
`rollback`([verbose])	Remove classes and instances from the underlying repository, that have been created in the local repository of this class.
`setns`(value)	Set the default repository namespace to be used.

Attributes:

default_namespace

The default repository namespace to be used.

CreateClass(*args, **kwargs)[source]

Create a CIM class in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.CreateClass().

CreateInstance(*args, **kwargs)[source]

Create a CIM instance in the local repository of this class. This implementation does not test for duplicate instances but appends each new instance to the repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateInstance().

DeleteClass(*args, **kwargs)[source]: This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

DeleteInstance(*args, **kwargs)[source]: This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

DeleteQualifier(*args, **kwargs)[source]: This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

EnumerateInstanceNames(*args, **kwargs)[source]: This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND. Because the operations of this class silently create every namespace that is needed and never return that error, this method is never called, and is therefore not implemented.

EnumerateQualifiers(*args, **kwargs)[source]

Enumerate the qualifier types in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateQualifiers().

GetClass(*args, **kwargs)[source]

Retrieve a CIM class from the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.GetClass().

GetQualifier(*args, **kwargs)[source]

Retrieve a qualifier type from the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.GetQualifier().

ModifyClass(*args, **kwargs)[source]: This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class. Because CreateClass() overwrites existing classes, this method is never called, and is therefore not implemented.

ModifyInstance(*args, **kwargs)[source]: This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance. Because CreateInstance() overwrites existing instances, this method is never called, and is therefore not implemented. NOTE: This error means that the mof compiler logic to attempt modifyinstance if createinstance fails does not attempt the modifyinstance.

SetQualifier(*args, **kwargs)[source]

Create or modify a qualifier type in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.SetQualifier().

property default_namespace

The default repository namespace to be used.

The default repository namespace is the default namespace of the underlying repository connection if there is such an underlying connection, or the default namespace of this object.

Initially, the default namespace of this object is ‘root/cimv2’.

This property is settable. Setting it will cause the default namespace of the underlying repository connection to be updated if there is such an underlying connection, or the default namespace of this object.

Type: string

getns()

string: Return the default repository namespace to be used.

This method exists for compatibility. Use the default_namespace property instead.

rollback(verbose=False)[source]

Remove classes and instances from the underlying repository, that have been created in the local repository of this class.

Limitations:

1. At this point, only classes and instances will be removed, but not qualifiers.

2. This may not work with instances created by other means, ex. other mof_compilers because of amgiguity in the definition of instance names for associations (ex. The namespace component in reference properties)

3. This only removes the classes specifically defined in the compiled mof and not any classes installed as prerquisits as part of the compile (ex. superclasses, classes defined by references)

setns(value)

Set the default repository namespace to be used.

This method exists for compatibility. Use the default_namespace property instead.

Exceptions

The MOF compiler API raises exceptions that are derived from the common base class MOFCompileError.

class pywbem.MOFCompileError(msg, parser_token=None)[source]

Base class for exceptions indicating issues with compiling MOF.

Derived from Error.

Parameters

msg (string) – Message text describing the error.
parser_token (lex.LexToken or yacc.YaccProduction) –
PLY lex or yacc parser token (that is, the p argument of a yacc parser function or the t argument of a lex parser function). This token is used to obtain the MOF source text and location information.

None will result in no MOF source text and location information to be obtained.

Attributes:

`__cause__`	exception cause
`__context__`	exception context
`column`	Position within the line in the MOF file or MOF string where the error occurred (1-based).
`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`context`	MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the '^' character to indicate the position of the token in error in the MOF line.
`file`	File name of the MOF file where the error occurred.
`lineno`	Line number in the MOF file or MOF string where the error occurred (1-based).
`msg`	Message text describing the error.

Methods:

`__delattr__`(name, /)	Implement delattr(self, name).
`__getattribute__`(name, /)	Return getattr(self, name).
`__new__`(**kwargs)
`__reduce__`	Helper for pickle.
`__repr__`()	Return repr(self).
`__setattr__`(name, value, /)	Implement setattr(self, name, value).
`__str__`()	Return str(self).
`get_err_msg`()	Return a multi-line error message for being printed, in the following format.
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

__str__()[source]: Return str(self).

property column

Position within the line in the MOF file or MOF string where the error occurred (1-based).

Type: integer

property context

MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the ‘^’ character to indicate the position of the token in error in the MOF line.

Type: string

property file

File name of the MOF file where the error occurred.

None if the error occurred in a MOF string that was compiled.

Type: string

get_err_msg()[source]

Return a multi-line error message for being printed, in the following format. The text in angle brackets refers to the same-named properties of the exception instance:

<error kind>:<file>:<lineno>:<colno>: <msg>
<context - MOF line>
<context - position indicator line>

Returns: Multi-line error message.
Return type: string

property lineno

Line number in the MOF file or MOF string where the error occurred (1-based).

Type: integer

property msg

Message text describing the error.

Type: string

class pywbem.MOFParseError(msg, parser_token=None)[source]

Exception indicating that MOF cannot be parsed correctly, e.g. for syntax errors.

Derived from MOFCompileError.

Parameters

msg (string) – Message text describing the error.
parser_token (lex.LexToken or yacc.YaccProduction) –
PLY lex or yacc parser token (that is, the p argument of a yacc parser function or the t argument of a lex parser function). This token is used to obtain the MOF source text and location information.

None will result in no MOF source text and location information to be obtained.

Attributes:

`__cause__`	exception cause
`__context__`	exception context
`column`	Position within the line in the MOF file or MOF string where the error occurred (1-based).
`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`context`	MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the '^' character to indicate the position of the token in error in the MOF line.
`file`	File name of the MOF file where the error occurred.
`lineno`	Line number in the MOF file or MOF string where the error occurred (1-based).
`msg`	Message text describing the error.

Methods:

`__delattr__`(name, /)	Implement delattr(self, name).
`__getattribute__`(name, /)	Return getattr(self, name).
`__new__`(**kwargs)
`__reduce__`	Helper for pickle.
`__repr__`()	Return repr(self).
`__setattr__`(name, value, /)	Implement setattr(self, name, value).
`__str__`()	Return str(self).
`get_err_msg`()	Return a multi-line error message for being printed, in the following format.
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.MOFDependencyError(msg, parser_token=None)[source]

Exception indicating that MOF cannot be compiled because of a missing dependency. For example, the MOF to be compiled specifies a class but the superclass of the class cannot be found.

Derived from MOFCompileError.

Parameters

msg (string) – Message text describing the error.
parser_token (lex.LexToken or yacc.YaccProduction) –
PLY lex or yacc parser token (that is, the p argument of a yacc parser function or the t argument of a lex parser function). This token is used to obtain the MOF source text and location information.

None will result in no MOF source text and location information to be obtained.

Attributes:

`__cause__`	exception cause
`__context__`	exception context
`column`	Position within the line in the MOF file or MOF string where the error occurred (1-based).
`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`context`	MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the '^' character to indicate the position of the token in error in the MOF line.
`file`	File name of the MOF file where the error occurred.
`lineno`	Line number in the MOF file or MOF string where the error occurred (1-based).
`msg`	Message text describing the error.

Methods:

`__delattr__`(name, /)	Implement delattr(self, name).
`__getattribute__`(name, /)	Return getattr(self, name).
`__new__`(**kwargs)
`__reduce__`	Helper for pickle.
`__repr__`()	Return repr(self).
`__setattr__`(name, value, /)	Implement setattr(self, name, value).
`__str__`()	Return str(self).
`get_err_msg`()	Return a multi-line error message for being printed, in the following format.
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class pywbem.MOFRepositoryError(msg, parser_token=None, cim_error=None)[source]

Exception indicating that MOF cannot be compiled because of a CIM error returned by the target CIM repository. The CIM error is attached to this exception and is part of the exception message.

Derived from MOFCompileError.

Parameters

msg (string) – Message text describing the error.
parser_token (lex.LexToken or yacc.YaccProduction) –
PLY lex or yacc parser token (that is, the p argument of a yacc parser function or the t argument of a lex parser function). This token is used to obtain the MOF source text and location information.

None will result in no MOF source text and location information to be obtained.
cim_error (CIMError) – CIM error returned by the CIM repository.

Attributes:

`__cause__`	exception cause
`__context__`	exception context
`cim_error`	CIM error returned by the CIM repository.
`column`	Position within the line in the MOF file or MOF string where the error occurred (1-based).
`conn_id`	Connection ID of the connection in whose context the error happened.
`conn_str`	String that identifies the connection in exception messages.
`context`	MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the '^' character to indicate the position of the token in error in the MOF line.
`file`	File name of the MOF file where the error occurred.
`lineno`	Line number in the MOF file or MOF string where the error occurred (1-based).
`msg`	Message text describing the error.

Methods:

`__delattr__`(name, /)	Implement delattr(self, name).
`__getattribute__`(name, /)	Return getattr(self, name).
`__new__`(**kwargs)
`__reduce__`	Helper for pickle.
`__repr__`()	Return repr(self).
`__setattr__`(name, value, /)	Implement setattr(self, name, value).
`__str__`()	Return str(self).
`get_err_msg`()	Return a multi-line error message for being printed, in the following format.
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

property cim_error

CIM error returned by the CIM repository.

Type: CIMError

get_err_msg()[source]

Return a multi-line error message for being printed, in the following format. The text in angle brackets refers to the same-named properties of the exception instance:

<error kind>:<file>:<lineno>:<colno>: <msg>
<context - MOF line>
<context - position indicator line>
<CIM error>

Returns: Multi-line error message.
Return type: string

Mock WBEM server

New in pywbem 0.12 as experimental and finalized in 1.2.

Overview

The ‘pywbem_mock’ module of pywbem provides a mock WBEM server that enables using the pywbem client library without a real WBEM server. This is useful for testing the pywbem client library itself as well as for the development and testing of Python programs that use the pywbem client library.

The pywbem_mock.FakedWBEMConnection class establishes an in-process mock WBEM server and represents a faked connection to that mock WBEM server. That class acts as both the client API and as an API for managing the mocked WBEM server.

The pywbem_mock.FakedWBEMConnection class is a subclass of pywbem.WBEMConnection and replaces its internal methods that use HTTP/HTTPS to communicate with a WBEM server with methods that communicate with the mock WBEM server. As a result, the operation methods of FakedWBEMConnection are those inherited from WBEMConnection, so they have exactly the same input parameters, output parameters, return values, and even most of the raised exceptions, as when invoked on a WBEMConnection object against a real WBEM server.

The mock WBEM server has an in-memory repository of CIM objects (the CIM repository). Each FakedWBEMConnection object creates its own CIM repository that contains the same kinds of CIM objects a WBEM server repository contains: CIM classes, CIM instances, and CIM qualifier declarations types, contained in CIM namespaces. Because FakedWBEMConnection operates only on the CIM repository, the class does not have any connection- or security-related constructor parameters.

Like WBEMConnection, FakedWBEMConnection has a default CIM namespace that is created in the CIM repository upon FakedWBEMConnection object creation. Additional namespaces in the CIM repository can be created with add_namespace() .

An Interop namespace can be created by adding it via add_namespace(). The Interop namespace will be initially empty, and the necessary instance(s) of a CIM namespace class will be automatically created when registering the namespace provider CIMNamespaceProvider. See Mocking multiple CIM namespaces for details.

The CIM repository must contain the CIM classes, CIM instances and CIM qualifier declaration types that are needed for the operations that are invoked. This results in a behavior of the mock WBEM server that is close to the behavior of the operations of a real WBEM server. FakedWBEMConnection has methods that provide for adding CIM classes, instances and qualifier types to its CIM repository by providing them as CIM objects, or by compiling MOF. See Building a mocked CIM repository for details.

The following example demonstrates setting up a mock WBEM server, adding several CIM objects defined in a MOF string to its CIM repository, and executing WBEM operations on the faked connection:

import pywbem
import pywbem_mock

# MOF string defining qualifiers, class, and instance
mof = '''
    Qualifier Key : boolean = false,
        Scope(property, reference),
        Flavor(DisableOverride, ToSubclass);
    Qualifier Description : string = null,
        Scope(any),
        Flavor(EnableOverride, ToSubclass, Translatable);
    Qualifier In : boolean = true,
        Scope(parameter),
        Flavor(DisableOverride, ToSubclass);

        [Description ("This is a dumb test class")]
    class CIM_Foo {
            [Key, Description ("This is key prop")]
        string InstanceID;
            [Description ("This is some simplistic data")]
        Uint32 SomeData;
            [Description ("This is a method without parameters")]
        string Fuzzy();
            [Description ("This is a second method with parameter")]
        uint32 Delete([IN, Description('blahblah']
          boolean Immediate);
    };

    instance of CIM_Foo as $I1 { InstanceID = "I1"; SomeData=3 };
    '''

# Create a faked connection including a mock WBEM server with a CIM repo
conn = pywbem_mock.FakedWBEMConnection(default_namespace='root/cimv2')

# Compile the MOF string and add its CIM objects to the default namespace
# of the CIM repository
conn.compile_mof_string(mof)

# Perform a few operations on the faked connection:

# Enumerate top-level classes in the default namespace (without subclasses)
classes = conn.EnumerateClasses();
for cls in classes:
    print(cls.tomof())

# Get the 'Description' qualifier type in the default namespace
qd = conn.GetQualifier('Description')

# Enumerate subclasses of 'CIM_Foo' in the default namespace (without subclasses)
classes2 = conn.EnumerateClasses(classname='CIM_Foo')

# Get 'CIM_Foo' class in the default namespace
my_class = conn.GetClass('CIM_Foo')

# Get a specific instance of 'CIM_Foo' in the default namespace
inst = conn.GetInstance(CIMInstanceName('CIM_Foo', {'InstanceID': "I1"}))

The mock WBEM server supports:

All of the WBEMConnection operation methods that communicate with the WBEM server (see below for the operations supported and their limitations).
Multiple CIM namespaces and a default namespace on the faked connection.
Gathering time statistics and delaying responses for a predetermined time.
WBEMConnection logging except that there are no HTTP entries in the log.
User-defined providers that replace the the default providers specific request methods, CIM classes, and namespaces. See User-defined providers.

The mock WBEM server does NOT support:

CIM-XML protocol security and security constructor parameters of WBEMConnection.
Processing of queries defined for ExecQuery() in languages like CQL and WQL. The mocked operation parses only the very general portions of the query for class/instance name and properties.
Filter processing of FQL (see DSP0212) the Filter Query Language parameter QueryFilter used by the Open… operations because it does not implement the parser/processor for the FQL language. It returns the same data as if the filter did not exist.
Providing data in the trace variables for last request and last reply in WBEMConnection: last_request, last_raw_request, last_reply, last_raw_reply, last_request_len, or last_reply_len.
Log entries for HTTP request and response in the logging support of WBEMConnection, because it does not actually build the HTTP requests or responses.
Generating CIM indications.
Some of the functionality that may be implemented in real WBEM servers such as the __Namespace__ class/provider. Note that such capabilities can be at least partly built on top of the existing capabilities by implementing user-defined providers. Thus the CIM_Namespace class is supported with the user defined provider in the pywbem_mock directory but only registered if the user wants to use the provider.

 +----------------------------------+
 |                                  |
 | +------------------------------+ |           +-------------+
 | |                              | |           |             |
 | | WBEM Server Mock Methods     | |           | Main        |
 | |                              | |           | Provider    |
 | |            All other Requests+------------>+             |
 | |  CreateInstance, ModifyInst  +------+      | Class ,assoc|
 | |  DeleteInstance, InvokeMeth  | |    |      | some inst   |
 | +------------^-----------------+ |    |      | requests    +--+
 |              |                   |    |      +-------------+  |
 | +------------+-----------------+ |    |                       |
 | | WBEM Server Mock Interface   | |    |      +-------------+  |     +-----------+
 | |                              | |    |      |             |  |     | Instance  |
 | +------------^-----------------+ |    |      | Provider    |  |     | Write     |
 |              |                   |    |      | Dispatcher  |  |     | Provider  |
 |              |                   |    |      |             +------->+ (Default) |
 |              |                   |    |      | Dispatches  |  |     +-|---|-----+       +----------+
 | +------------+-----------------+ |    |      | methods to  |  | +-----|   |-------------+ User     |
 | |                              | |    +----->+ default or  +----------------------------> Instance |
 | |  Client API request methods  | |           | registered  |  | |                       | Providers|
 | |  from WBEM Connection        | |           | user        |  | |   +------------+      |          +-----+
 | |                              | |           | providers   |  | |   |            |      +----------+     |
 | |   ..CreateClass, etc.        | |           |             +------->+ Method     |                       |
--->                              | |           |             |  | |   | Provider   |                       |
 | |                              | |           |             |  | |   | (Default)  |                       |
 | |                              | |           +-----------+-+  | |   +-----|------+                       |
 | +------------------------------+ |                       |    | |         |------------------------+     |
 | +------------------------------+ |                       +-------------------------------> User    |     |
 | |  Mock Environment management | |                            | |                        | Method  |     |
 | |  methods                     | |                            | |                        | Providers     |
 | |  * Mof Compiler, add objects | |                            | |                        |         |     |
 | |  * Manage namespaces         | |                            | |                        +---------+     |
 | |  * Register user providers   +---------+    +---------------v-V----------------------------------+     |
 | +------------------------------+ |       |    |                                                    |     |
 |  FakedWBEMConnection             |       +---->          CIM Repository                            <-----+
 +----------------------------------+            |                                                    |
                                                 +----------------------------------------------------+

Diagram of flow of requests operations through mocker

WBEM operations of a mock WBEM server

The pywbem_mock.FakedWBEMConnection class supports the same WBEM operations that are supported by the pywbem.WBEMConnection class and in addition a set of methods for setting up its mocked CIM repository, and for registering user-defined providers for selected WBEM operations.

These faked WBEM operations generally adhere to the behavior requirements defined in DSP0200 for handling input parameters and returning a result.

The faked WBEM operations get the data to be returned from the CIM repository of the mock WBEM server, and put the data provided in operation parameters that modify objects (create, modify, and delete operations) into the CIM repository.

However, because the pywbem mock support is only a simulation of a WBEM server and intended to be used primarily for testing, there are limitations and differences between the behavior of the faked WBEM operations and a real WBEM server.

The descriptions below describe differences between the faked WBEM operations of the pywbem mock support and the operations of a real WBEM server, and the effects of the operation modes of the CIM repository.

Faked instance operations

The operations that retrieve instances require instances in the repository for the instances to be recovered and that the classes for these instances exist in the repository.

GetInstance: Behaves like GetInstance(). Returns an instance defined by the instance name input parameter if that instance exists in the repository.
EnumerateInstances: Behaves like EnumerateInstances(), returning all instances of the CIM class defined on input and subclasses of this class filtered by the optional attributes for property names, etc.
EnumerateInstanceNames: Behaves like EnumerateInstances(), Returns the instance name of all instances of the pywbem.CIMClass defined on input and subclasses of this class.
CreateInstance: Behaves like CreateInstance().

Creates the defined instance in the CIM repository.

If there is no user-defined provider (see User-defined providers)for the class defined in the NewInstance parameter operation requires that all key properties be specified in the new instance since the CIM repository has no support for dynamically setting key properties and all key properties are required to get the newly defined instance with other requests. If a user-defined provider exists for the class, the behavior depends on that provider.
ModifyInstance: Behaves like ModifyInstance(). Modifies the instance defined by the instance name provided on input if that instance exists in the repository. It modifies only the properties defined by the instance provided and will not modify any key properties. If there is a user-defined provider defined for this operation, that provider may modify the default behavior.
DeleteInstance: Behaves like DeleteInstance(). Deletes the instance defined by the instance name provided on input if that instance exists. If there is a user-defined provider defined for this operation, that provider may modify the default behavior.
ExecQuery: This operation is not currently implemented.

See User-defined providers for more information on writing a user-defined provider.

Faked association operations

The faked association operations support both instance-level use and class-level requests. Class-level use requires the CIM repository to be in full mode, while instance-level use works in both operation modes of the CIM repository.

AssociatorNames: Behaves like AssociatorNames(), with the following requirements: The source, target, and association classes and their subclasses must exist in the CIM repository for both class-level use and instance-level use.
Associators: Behaves like Associators(), with the requirements described for AssociatorNames, above.
ReferenceNames: Behaves like ReferenceNames(), with the requirements described for AssociatorNames, above.
References: Behaves like References(), with the requirements described for AssociatorNames, above.

Faked method invocation operation

The faked method invocation operation (InvokeMethod) behaves like InvokeMethod(), but because of the nature of InvokeMethod, the user must provide an implementation of InvokeMethod based on the API defined in InvokeMethod().

NOTE: InvokeMethod is the method name pywbem and other clients and WBEM servers use for what the DMTF defines as extrinsic methods.

See User-defined providers for more information on writing a user-defined provider.

Faked pull operations

The faked pull operations behave like the pull operations of WBEMConnection, with the following exceptions:

The filter query related parameters FilterQuery and FilterQueryLanguage are ignored and no such filtering takes place.
The ContinueOnError parameter is ignored because injecting an error into the processing of the pull operations is not supported by the pywbem mock support, so no failures can happen during the processing of the pull operations.
The OperationTimeout parameter is currently ignored. As a result, there will be no timeout if the response_delay property is set to a time larger than the OperationTimeout parameter.

The faked pull operations are:

OpenEnumerateInstances: Behaves like OpenEnumerateInstances(), with the stated exceptions.
OpenEnumerateInstancePaths: Behaves like OpenEnumerateInstancePaths(), with the stated exceptions.
OpenAssociatorInstances: Behaves like OpenAssociatorInstances(), with the stated exceptions.
OpenAssociatorInstancePaths: Behaves like OpenAssociatorInstancePaths(), with the stated exceptions.
OpenReferenceInstances: Behaves like OpenReferenceInstances(), with the stated exceptions.
OpenReferenceInstancePaths: Behaves like OpenReferenceInstancePaths(), with the stated exceptions.
OpenQueryInstances: Behaves like OpenQueryInstances(), with the stated exceptions.
PullInstancesWithPath: Behaves like PullInstancesWithPath(), with the stated exceptions.
PullInstancePaths: Behaves like PullInstancePaths(), with the stated exceptions.
PullInstances: Behaves like PullInstances(), with the stated exceptions.
CloseEnumeration: Behaves like CloseEnumeration(), with the stated exceptions.

Faked iter operations

The iter operations on a faked connection are in fact the iter operations on WBEMConnection, because they do not directly issue requests and responses on the connection, but instead are a layer on top of underlying operations. For example, IterEnumerateInstances invokes either pull operations (i.e. OpenEnumerateInstances followed by PullInstancesWithPath) or traditional operations (i.e. EnumerateInstances). The use of pull vs. traditional operations is controlled via the use_pull_operations init parameter of FakedWBEMConnection.

The iter operations are:

Faked class operations

Class operations only work if the CIM repository is in full operation mode.

GetClass: Behaves like GetClass(). Requires that the class to be returned is in the CIM repository.
EnumerateClasses: Behaves like EnumerateClasses(). Requires that the class specified in the ClassName parameter be in the CIM repository.
EnumerateClassNames: Behaves like EnumerateClassNames(). Requires that the class specified in the ClassName parameter be in the CIM repository.
CreateClass: Behaves like CreateClass(). Requires that the superclass of the new class (if it specifies one) is in the CIM repository.
DeleteClass: Behaves like DeleteClass(), with the following difference: This operation additionally deletes all direct and indirect subclasses of the class to be deleted, and all instances of the classes that are being deleted. Requires that the class to be deleted is in the CIM repository.
ModifyClass: Behaves like ModifyClass(). The pywbem_mock implementation rejects modifications where the class to modifiy has either subclasses or instances and resolves the various qualifiers, class origin values and propagated values as the the CreateClass operation.

Faked qualifier declaration operations

Qualifier operations declaration include the following.

SetQualifier: Behaves like SetQualifier(). Requires that the specified qualifier type is in the CIM repository.
GetQualifier: Behaves like GetQualifier(). Requires that the specified qualifier type is in the CIM repository.
EnumerateQualifiers: Behaves like EnumerateQualifiers(). Requires that the qualifier types to be returned are in the CIM repository.
DeleteQualifier: - Not implemented.

FakedWBEMConnection class

class pywbem_mock.FakedWBEMConnection(default_namespace='root/cimv2', use_pull_operations=False, stats_enabled=False, timeout=None, response_delay=None, disable_pull_operations=None, url=None)[source]

A subclass of pywbem.WBEMConnection that mocks the communication with a WBEM server by utilizing a local in-memory CIM repository to generate responses in the same way the WBEM server would.

New in pywbem 0.12 as experimental and finalized in 1.2.

Each FakedWBEMConnection object has its own CIM repository which contains multiple CIM namespaces, and each namespace may contain CIM qualifier types (declarations), CIM classes and CIM instances.

This class provides only a subset of the init parameters of WBEMConnection because it does not have a connection to a WBEM server. It uses a faked and fixed URL for the WBEM server (http://FakedUrl) as a means of identifying the connection by users.

Logging of the faked operations is supported via the pywbem logging facility and can be controlled in the same way as for WBEMConnection. For details, see WBEM operation logging.

Some of the longer running methods of this class add time statistics to the pywbem.WBEMConnection.statistics. For details on how to get the statistics, see WBEM operation statistics.

Parameters

default_namespace (string) – Default namespace. This parameter has the same characteristics as the same-named init parameter of WBEMConnection.
use_pull_operations (bool) – Flag to control whether pull or traditional operations are used in the iter… operations. This parameter has the same characteristics as the same-named init parameter of WBEMConnection.
timeout (number) – This parameter has the same characteristics as the same-named init parameter of WBEMConnection.
stats_enabled (bool) – Flag to enable operation statistics. This parameter has the same characteristics as the same-named init parameter of WBEMConnection.
response_delay (number) –
Artifically created delay for each operation, in seconds. This must be a positive number. Delays less than a second or other fractional delays may be achieved with float numbers. None disables the delay.

Note that the response_delay property can be used to set this delay subsequent to object creation.
disable_pull_operations (bool) –
Flag to allow user to disable the pull operations ( Open… and Pull.. requests). The default is None which enables pull operations to execute. Setting the flag to True causes pull operations to raise CIMError(CIM_ERR_NOT_SUPPORTED).

The disable_pull_operations property can be used to set this variable.

url (string):: Defines a url to replace the default http://FakedURL.5988 url which is passed to the superclass. The url must be an acceptable syntax for WBEMConnection initialization. This is useful when multiple mocks are required for testing.

Raises: ValueError – Invalid arguments

Methods:

`AssociatorNames`(ObjectName[, AssocClass, ...])	Retrieve the instance paths of the instances associated to a source instance, or the class paths of the classes associated to a source class.
`Associators`(ObjectName[, AssocClass, ...])	Retrieve the instances associated to a source instance, or the classes associated to a source class.
`CloseEnumeration`(context)	Close an open enumeration session, causing an early termination of an incomplete enumeration session.
`CreateClass`(NewClass[, namespace])	Create a class in a namespace.
`CreateInstance`(NewInstance[, namespace])	Create an instance in a namespace.
`DeleteClass`(ClassName[, namespace])	Delete a class.
`DeleteInstance`(InstanceName)	Delete an instance.
`DeleteQualifier`(QualifierName[, namespace])	Delete a qualifier type (= qualifier declaration).
`EnumerateClassNames`([namespace, ClassName, ...])	Enumerate the names of subclasses of a class, or of the top-level classes in a namespace.
`EnumerateClasses`([namespace, ClassName, ...])	Enumerate the subclasses of a class, or the top-level classes in a namespace.
`EnumerateInstanceNames`(ClassName[, namespace])	Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.
`EnumerateInstances`(ClassName[, namespace, ...])	Enumerate the instances of a class (including instances of its subclasses) in a namespace.
`EnumerateQualifiers`([namespace])	Enumerate the qualifier types (= qualifier declarations) in a namespace.
`ExecQuery`(QueryLanguage, Query[, namespace])	Execute a query in a namespace.
`ExportIndication`(NewIndication)	Send an indication to a WBEM listener.
`GetClass`(ClassName[, namespace, LocalOnly, ...])	Retrieve a class.
`GetInstance`(InstanceName[, LocalOnly, ...])	Retrieve an instance.
`GetQualifier`(QualifierName[, namespace])	Retrieve a qualifier type (= qualifier declaration).
`InvokeMethod`(MethodName, ObjectName[, Params])	Invoke a method on a target instance or on a target class.
`IterAssociatorInstancePaths`(InstanceName[, ...])	Retrieve the instance paths of the instances associated to a source instance, using the Python generator idiom to return the result.
`IterAssociatorInstances`(InstanceName[, ...])	Retrieve the instances associated to a source instance, using the Python generator idiom to return the result.
`IterEnumerateInstancePaths`(ClassName[, ...])	Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result.
`IterEnumerateInstances`(ClassName[, ...])	Enumerate the instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result.
`IterQueryInstances`(FilterQueryLanguage, ...)	Execute a query in a namespace, using the Python generator idiom to return the result.
`IterReferenceInstancePaths`(InstanceName[, ...])	Retrieve the instance paths of the association instances that reference a source instance, using the Python generator idiom to return the result.
`IterReferenceInstances`(InstanceName[, ...])	Retrieve the association instances that reference a source instance, using the Python generator idiom to return the result.
`ModifyClass`(ModifiedClass[, namespace])	Modify a class.
`ModifyInstance`(ModifiedInstance[, ...])	Modify the property values of an instance.
`OpenAssociatorInstancePaths`(InstanceName[, ...])	Open an enumeration session to retrieve the instance paths of the instances associated to a source instance.
`OpenAssociatorInstances`(InstanceName[, ...])	Open an enumeration session to retrieve the instances associated to a source instance.
`OpenEnumerateInstancePaths`(ClassName[, ...])	Open an enumeration session to enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.
`OpenEnumerateInstances`(ClassName[, ...])	Open an enumeration session to enumerate the instances of a class (including instances of its subclasses) in a namespace.
`OpenQueryInstances`(FilterQueryLanguage, ...)	Open an enumeration session to execute a query in a namespace and to retrieve the instances representing the query result.
`OpenReferenceInstancePaths`(InstanceName[, ...])	Open an enumeration session to retrieve the instance paths of the association instances that reference a source instance.
`OpenReferenceInstances`(InstanceName[, ...])	Open an enumeration session to retrieve the association instances that reference a source instance.
`PullInstancePaths`(context, MaxObjectCount)	Retrieve the next set of instance paths from an open enumeration session.
`PullInstances`(context, MaxObjectCount)	Retrieve the next set of instances (without instance paths) from an open enumeration session.
`PullInstancesWithPath`(context, MaxObjectCount)	Retrieve the next set of instances (with instance paths) from an open enumeration session.
`ReferenceNames`(ObjectName[, ResultClass, Role])	Retrieve the instance paths of the association instances that reference a source instance, or the class paths of the association classes that reference a source class.
`References`(ObjectName[, ResultClass, Role, ...])	Retrieve the association instances that reference a source instance, or the association classes that reference a source class.
`SetQualifier`(QualifierDeclaration[, namespace])	Create or modify a qualifier type (= qualifier declaration) in a namespace.
`__enter__`()	New in pywbem 1.2.
`__exit__`(exc_type, exc_value, traceback)	New in pywbem 1.2.
`__repr__`()	Return a representation of the `WBEMConnection` object with all attributes (except for the password in the credentials) that is suitable for debugging.
`__str__`()	Return a short representation of the `WBEMConnection` object for human consumption.
`add_cimobjects`(objects[, namespace])	Add CIM classes, instances and/or CIM qualifier types (declarations) to the specified CIM namespace of the CIM repository.
`add_namespace`(namespace[, verbose])	Add a CIM namespace to the CIM repository of the faked connection.
`add_operation_recorder`(operation_recorder)	Internal: Add an operation recorder to this connection.
`close`()	Closes this connection.
`compile_mof_file`(mof_file[, namespace, ...])	Compile the MOF definitions in the specified file (and its included files) and add the resulting CIM objects to the specified CIM namespace of the CIM repository.
`compile_mof_string`(mof_str[, namespace, ...])	Compile the MOF definitions in the specified string and add the resulting CIM objects to the specified CIM namespace of the CIM repository.
`compile_schema_classes`(class_names, ...[, ...])	Compile the classes defined by class_names and all of their dependences.
`copy`()	New in pywbem 1.3.
`display_registered_providers`()	Display information on the currently registered providers.
`display_repository`([namespaces, dest, ...])	Display the namespaces and objects in the CIM repository in one of multiple formats to a destination.
`find_interop_namespace`()	Find the Interop namespace in the CIM repository, or return None.
`install_namespace_provider`(interop_namespace)	FakedWBEMConnection user method to install the namespace provider in the Interop namespace where the proposed interop_namespace is defined by the parameter interop_namespace
`install_subscription_providers`(interop_namespace)	FakedWBEMConnection user method to install the indication subscription providers in the Interop namespace where the proposed interop_namespace is defined by the parameter interop_namespace
`is_interop_namespace`(namespace)	Tests if a namespace name is a valid Interop namespace name.
`is_subclass`(namespace, klass, superclass)	Return boolean indicating whether a class is a (direct or indirect) subclass of a superclass, or the same class, in the specified namespace.
`operation_recorder_reset`([pull_op])	Internal: Low-level method used by the operation-specific methods of this class.
`operation_recorder_stage_pywbem_args`(method, ...)	Internal: Low-level method used by the operation-specific methods of this class.
`operation_recorder_stage_result`(ret, exc)	Internal: Low-level method used by the operation-specific methods of this class.
`register_provider`(provider[, namespaces, ...])	Register the provider object for specific namespaces and CIM classes.
`remove_namespace`(namespace[, verbose])	Remove a CIM namespace from the CIM repository of the faked connection.

Attributes:

`ca_certs`	Selects the CA certificates (trusted certificates) for verifying the X.509 server certificate returned by the WBEM server or WBEM listener.
`cimrepository`	The mocked in-memory CIM repository.
`conn_id`	connection id: Connection ID (a unique ID) of this connection.
`creds`	Credentials for HTTP authentication with the WBEM server.
`debug`	Boolean indicating that debug is enabled for this connection.
`default_namespace`	Name of the CIM namespace to be used by default (if no namespace is specified for an operation).
`disable_pull_operations`	`bool`: Boolean flag to set option to disable the execution of the open and pull operation request handlers in the CIM repository.
`host`	Normalized host and port number of the WBEM server or WBEM listener, in the format `host:port`.
`interop_namespace_names`	NocaseList of string: The valid Interop namespace names.
`last_operation_time`	Elapsed time of the last operation that was executed via this connection in seconds or None.
`last_raw_reply`	unicode string: CIM-XML data of the last response received from the WBEM server or WBEM listener on this connection, formatted as it was received (=raw).
`last_raw_request`	unicode string: CIM-XML data of the last request sent to the WBEM server or WBEM listener on this connection, formatted as it was sent (=raw).
`last_reply`	unicode string: CIM-XML data of the last response received from the WBEM server or WBEM listener on this connection, formatted as prettified XML.
`last_reply_len`	`int`: The size of the HTTP body in the CIM-XML response of the last operation, in Bytes.
`last_request`	unicode string: CIM-XML data of the last request sent to the WBEM server or WBEM listener on this connection, formatted as prettified XML.
`last_request_len`	`int`: The size of the HTTP body in the CIM-XML request of the last operation, in Bytes.
`last_server_response_time`	Server-measured response time of the last request, or None.
`namespaces`	NocaseList of string: The names of the namespaces that exist in the CIM repository.
`no_verification`	Boolean indicating that verifications are disabled for this connection.
`operation_recorder_enabled`	Internal: Enablement status for all operation recorders of the connection.
`operation_recorders`	Tuple of `BaseOperationRecorder` subclass objects:
`provider_dependent_registry`	The registry for provider dependent files, in context of a mock script.
`proxies`	Dictionary with the URLs of HTTP or SOCKS proxies to use for the connection to the WBEM server or WBEM listener.
`response_delay`	number: Artifically created delay for each operation, in seconds.
`scheme`	Normalized scheme of the URL of the WBEM server or WBEM listener, for example 'http' or 'https'.
`statistics`	Statistics for this connection.
`stats_enabled`	Statistics enablement status for this connection.
`timeout`	Timeout in seconds, for requests sent to the server or listener.
`url`	Normalized URL of the WBEM server or WBEM listener.
`use_pull_operations`	Boolean indicating that the client should attempt the use of pull operations in any Iter...() methods.
`x509`	X.509 client certificate and key file to be presented to the WBEM server or WBEM listener during the TLS/SSL handshake.

__repr__()[source]: Return a representation of the WBEMConnection object with all attributes (except for the password in the credentials) that is suitable for debugging.

__str__()[source]: Return a short representation of the WBEMConnection object for human consumption.

add_cimobjects(objects, namespace=None)[source]

Add CIM classes, instances and/or CIM qualifier types (declarations) to the specified CIM namespace of the CIM repository.

This method adds a copy of the objects presented so that the user may modify the objects without impacting the repository.

If the namespace does not exist, CIMError with status CIM_ERR_INVALID_NAMESPACE is raised.

The method imposes very few limits on the objects added. It does require that the superclass exist for any class added and that instances added include a path component. If the qualifier flavor attributes are not set, it sets them to those defined in the Qualifier Declarations if those exist.

If a CIM class or CIM qualifier type to be added already exists in the target namespace with the same name (comparing case insensitively), this method fails, and the CIM repository remains unchanged.

If a CIM instance to be added already exists in the target namespace with the same keybinding values, this method fails, and the CIM repository remains unchanged.

Parameters

objects (CIMClass or CIMInstance or CIMQualifierDeclaration, or list of them) – CIM object or objects to be added to the CIM repository. The list may contain different kinds of CIM objects.
namespace (string) – The name of the target CIM namespace in the CIM repository. This namespace is also used for lookup of any existing or dependent CIM objects. If None, the default namespace of the connection is used.

Raises

ValueError – Invalid input CIM object in objects parameter.
TypeError – Invalid type in objects parameter.
CIMError – CIM_ERR_INVALID_NAMESPACE: Namespace does not exist.
CIMError – Failure related to the CIM objects in the CIM repository.

add_namespace(namespace, verbose=False)[source]

Add a CIM namespace to the CIM repository of the faked connection.

The namespace must not yet exist in the CIM repository.

Parameters

namespace (string) – The name of the CIM namespace to be added to the CIM repository. Must not be None. Any leading or trailing slash characters are removed before the string is used to define the namespace name.
verbose (bool) – Verbose mode: Print a message about the namespace creation.

Raises

ValueError – Namespace argument must not be None.
CIMError – CIM_ERR_ALREADY_EXISTS if the namespace already exists in the CIM repository.

property cimrepository

The mocked in-memory CIM repository.

The CIM repository is the data store for CIM classes, CIM instances, and CIM qualifier declarations, all partitioned by CIM namespaces.

Type: InMemoryRepository

compile_mof_file(mof_file, namespace=None, search_paths=None, verbose=None)[source]

Compile the MOF definitions in the specified file (and its included files) and add the resulting CIM objects to the specified CIM namespace of the CIM repository.

If the namespace does not exist, CIMError with status CIM_ERR_INVALID_NAMESPACE is raised.

This method supports all MOF pragmas, and specifically the include pragma.

If a CIM class or CIM qualifier type to be added already exists in the target namespace with the same name (comparing case insensitively), this method raises CIMError.

If a CIM instance to be added already exists in the target namespace with the same keybinding values, this method raises CIMError.

In all cases where this method raises an exception, the CIM repository remains unchanged.

Parameters

mof_file (string) – Path name of the file containing the MOF definitions to be compiled.
namespace (string) – The name of the CIM namespace in the associated CIM repository that is the target of the compilation, and is also used for lookup of any dependent CIM elements. If None, the default namespace of the connection is used. A namespace defined in a namespace pragma of the MOF superceeds this namespace from the point in the compilation unit(string/file) where it is declared. The namespace specified in this parameter or the MOF inamespace pragma must exist.
search_paths (iterable of string) – An iterable of directory path names where MOF dependent files will be looked up. See the description of the search_path init parameter of the MOFCompiler class for more information on MOF dependent files.
verbose (bool) – Controls whether to issue more detailed compiler messages.

Raises

IOError – MOF file not found.
MOFCompileError – Compile error in the MOF.

compile_mof_string(mof_str, namespace=None, search_paths=None, verbose=None)[source]

Compile the MOF definitions in the specified string and add the resulting CIM objects to the specified CIM namespace of the CIM repository.

If the namespace does not exist, CIMError with status CIM_ERR_INVALID_NAMESPACE is raised.

This method supports all MOF pragmas, and specifically the include pragma.

If a CIM class or CIM qualifier type to be added already exists in the target namespace with the same name (comparing case insensitively), this method raises CIMError.

If a CIM instance to be added already exists in the target namespace with the same keybinding values, this method raises CIMError.

In all cases where this method raises an exception, the CIM repository remains unchanged.

Parameters

mof_str (string) – A string with the MOF definitions to be compiled.
namespace (string) – The name of the CIM namespace in the associated CIM repository that is the target of the compilation, and is also used for lookup of any dependent CIM elements. If None, the default namespace of the connection is used. A namespace defined in a namespace pragma of the MOF superceeds this namespace from the point in the compilation unit(string/file) where it is declared. The namespace specified in this parameter or the MOF inamespace pragma must exist.
search_paths (iterable of string) – An iterable of directory path names where MOF dependent files will be looked up. See the description of the search_path init parameter of the MOFCompiler class for more information on MOF dependent files.
verbose (bool) – Controls whether to issue more detailed compiler messages.

Raises

IOError – MOF file not found.
MOFCompileError – Compile error in the MOF.

compile_schema_classes(class_names, schema_pragma_files, namespace=None, verbose=False)[source]

Compile the classes defined by class_names and all of their dependences. The class names must be classes in the defined schema and with pragma statements in a schema pragma file. Each schema pragma file in the schema_pragma_files parameter must be in a directory that also encompasses the MOF files for all of the classes defined in the schema pragma file and the dependencies of those classes. While the relative paths of all of the CIM class files is defined in the schema_pragma_file the pywbem MOF compiler may also search for dependencies (ex. superclasses, references, etc.) that are not specifically listed in the class_names and the path of the schema_pragma_file is the top level directory for that search. The mof schema directory must include:

Qualifier declarations defined in a single file with the name qualifiers.mof defined within the directory defined by the schema_mof_dir parameter
The file schema_pragma_file that defines the location of all of the CIM class files within the a schema mof directory hierarchy. This is the schema_pragma_file attribute of the DMTFCIMSchema class.
The MOF files, one for each class, for the classes that could be compiled within the directory hierarchy defined by schema_mof_dir.

Only the leaf class names need be included in the class_names list since the compiler will find all dependencies as part of the dependency resolution for the compile of each class in class_names.

Parameters

class_names (string or list of string) – Class names of the classes to be compiled. These class names must be a subset of the classes defined in schema_pragma_file.
schema_pragma_files (string or list of string) – Relative or absolute file path(s) of schema pragma files that include a MOF pragma include statement for each CIM class to be compiled. This file path is available from pywbem_mock.DMTFCIMSchema.schema_pragma_file.
namespace (string) – The name of the CIM namespace in the associated CIM repository that is the target of the compilation, and is also used for lookup of any dependent CIM elements. If None, the default namespace of the connection is used. A namespace defined in a namespace pragma of the MOF superceeds this namespace from the point in the compilation unit(string/file) where it is declared. The namespace specified in this parameter or the MOF inamespace pragma must exist.
verbose (bool) – If True, progress messages are output to stdout as the schema is downloaded and expanded. Default is False.

Raises

MOFCompileError – For errors in MOF parsing, finding MOF dependencies or issues with the CIM repository.
CIMError – Other errors relating to the target server environment.

copy()[source]

New in pywbem 1.3.

Return a deep copy of the object with internal state reset and reusing the same repository and registries.

The returned object uses the same repository, provider registry and provider dependent registry objects as the original object. Besides that, all other user-specifiable attributes of the object are deep-copied, and all other internal state is reset.

property disable_pull_operations

bool: Boolean flag to set option to disable the execution of the open and pull operation request handlers in the CIM repository. This emulates the characteristic in some CIM servers that did not implement pull operations. The default is to allow pull operations. All pull operations requests may be forbidden from executing by setting disable_pull_operations to True.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

display_registered_providers()[source]

Display information on the currently registered providers.

Parameters: dest (string) – File path of an output file. If None, the output is written to stdout.

display_repository(namespaces=None, dest=None, summary=False, output_format='mof')[source]

Display the namespaces and objects in the CIM repository in one of multiple formats to a destination.

Parameters

namespaces (string or list of string) – Limits display output to the specified CIM namespace or namespaces. If None, all namespaces of the CIM repository are displayed.
dest (string) – File path of an output file. If None, the output is written to stdout.
summary (bool) – Flag for summary mode. If True, only a summary count of CIM objects in the specified namespaces of the CIM repository is produced. If False, both the summary count and the details of the CIM objects are produced.
output_format (string) – Output format, one of: ‘mof’, ‘xml’, or ‘repr’.

find_interop_namespace()[source]

Find the Interop namespace in the CIM repository, or return None.

The Interop namespace is identified by comparing all namespace names in the CIM repository against the list of valid Interop namespace names returned by interop_namespace_names().

Returns: The name of the Interop namespace if one exists in the CIM repository or otherwise None.
Return type: string

install_namespace_provider(interop_namespace, schema_pragma_file=None, verbose=None)[source]

FakedWBEMConnection user method to install the namespace provider in the Interop namespace where the proposed interop_namespace is defined by the parameter interop_namespace

Because this provider requires a set of classes from the DMTF schema, the schema_pragma_file install the schema is required.

This method should only be called once at the creation of the mock environment.

Parameters

interop_namespace (string) – The Interop namespace defined for this environment
schema_pragma_file (string) –
File path defining a CIM schema pragma file for the set of CIM classes that make up a schema such as the DMTF schema. This file must contain a pragma statement for each of the classes defined in the schema.

If None, no attempt is made to any CIM classes required for the provider and it is assumed that the CIM classes are already installed
verbose (bool) – If True, displays progress information as providers are installed.

Raises

CIMError – with status code appropriate for any error encountered in the installation of the provider.

install_subscription_providers(interop_namespace, schema_pragma_file=None, verbose=None)[source]

FakedWBEMConnection user method to install the indication subscription providers in the Interop namespace where the proposed interop_namespace is defined by the parameter interop_namespace

Experimental: New in pywbem 1.3.0 as experimental.

Because these provider requires a set of classes from the DMTF schema, the schema_pragma_file install the schema is required.

This method should only be called once at the creation of the mock environment.

Parameters

interop_namespace (string) – The Interop namespace defined for this environment
schema_pragma_file (string) –
File path defining a CIM schema pragma file for the set of CIM classes that make up a schema such as the DMTF schema. This file must contain a pragma statement for each of the classes defined in the schema.

If None, no attempt is made to any CIM classes required for the provider and it is assumed that the CIM classes are already installed
verbose (bool) – If True, displays progress information as providers are installed.

Raises

CIMError – with status code appropriate for any error encountered in the installation of the provider.

property interop_namespace_names

NocaseList of string: The valid Interop namespace names.

Only these names may be the Interop namespace and only one Interop namespace may exist in a WBEM server environment. This list is defined in pywbem.WBEMServer.INTEROP_NAMESPACES.

is_interop_namespace(namespace)[source]

Tests if a namespace name is a valid Interop namespace name.

This method does not access the CIM repository for this test; it merely compares the specified namespace name against the list of valid Interop namespace names returned by interop_namespace_names().

Parameters: namespace (string) – The namespace name that is to be tested.
Returns: Indicates whether the namespace name is a valid Interop namespace name.
Return type: bool

property namespaces: NocaseList of string: The names of the namespaces that exist in the CIM repository.

property provider_dependent_registry

The registry for provider dependent files, in context of a mock script.

Type: ProviderDependentRegistry

register_provider(provider, namespaces=None, schema_pragma_files=None, verbose=None)[source]

Register the provider object for specific namespaces and CIM classes. Registering a provider tells the FakedWBEMConnection that the provider implementation provided with this method as the provider parameter is to be executed as the request response method for the namespaces defined in the namespaces parameter, the provider type defined in the ‘provider_type` attribute of the provider and the class(es) defined in the provider provider_classnames attribute of the provider.

The provider registration process includes:

Validation that the namespaces defined for the provider exist.
Validation that the superclass of the provider is consistent with the provider_type attribute defined in the provider.
Installation of any CIM classes defined by the provider provider_classnames attribute including dependencies for these classes using the schema_pragma_files parameter to define the MOF compiler search directories for dependencies.
Adding the provider to the registry of user_providers so that any of the request methods defined for the provider_type are passed to this provider in place of the default request processors.
Execute post_register_setup() call to the provider to allow the provider to perform any special setup functionality.

Providers can only be registered for the following request response methods:

provider_type = ‘instance’: defines methods for CreateInstance, ModifyInstance, and DeleteInstance requests within a subclass of the InstanceWriteProvider class.
provider_type = ‘method’: defines a InvokeMethod method within a subclass of the MethodProvider class.

Each classname in a particular namespace may have at most one provider registered

Parameters

provider (instance of subclass of pywbem_mock.InstanceWriteProvider or pywbem_mock.MethodProvider) – An instance of the user provider class which is a subclass of pywbem_mock.InstanceWriteProvider. The methods in this subclass override the corresponding methods in InstanceWriteProvider. The method call parameters must be the same as the defult method in InstanceWriteProvider and it must return data in the same format if the default method returns data.
namespaces (string or list of string) –
Namespace or namespaces for which the provider is to be registered.

If None, the default namespace of the connection will be used.
schema_pragma_files (string or list of string) –
File paths defining a schema pragma file MOF for the set of CIM classes that make up a schema such as the DMTF schema. These files must contain include pragma statements defining the file location of the classes to be compiled for the defined provider and for any dependencies required to compile those classes. The directory containing each schema pragma file is passed to the MOF compiler as the search path for compile dependencies.

See pywbem.MOFCompiler for more information on the search_paths parameter.
verbose (bool) – Flag to enable detailed display of actions

Raises

TypeError – Invalid provider_type retrieved from provider or provider_type does not match superlclass or the namespace parameter is invalid.
ValueError – Provider_type retrieved from provider is not a valid string.
ValueError – Classnames parameter retrieved from provider not a valid string or iterable or namespace does not exist in repository.

remove_namespace(namespace, verbose=False)[source]

Remove a CIM namespace from the CIM repository of the faked connection.

The namespace must exist in the CIM repository and must be empty.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository (case insensitive). Must not be None. Leading or trailing slash characters are ignored.
verbose (bool) – Verbose mode: Print a message about the namespace deletion.

Raises

ValueError – Namespace argument must not be None
CIMError – (CIM_ERR_NOT_FOUND) if the namespace does not exist in the CIM repository.
CIMError – (CIM_ERR_NAMESPACE_NOT_EMPTY) if the namespace is not empty.
CIMError – (CIM_ERR_NAMESPACE_NOT_EMPTY) if attempting to delete the default connection namespace. This namespace cannot be deleted from the CIM repository

property response_delay

number: Artifically created delay for each operation, in seconds. If None, there is no delay.

This attribute is settable. For details, see the description of the same-named init parameter of this class.

Building a mocked CIM repository

The CIM repository of a mock WBEM server needs to contain the CIM namespaces, and within them, the CIM qualifier declarations, CIM classes, and CIM instances required by the user. These are created as part of the setup of any particular pywbem mock environment. Thus, if the user only requires CIM_ComputerSystem in a particular namespace, only that class and its dependent classes and qualifier declarations need be in that namespace in the CIM repository, along with instances of the classes that will satisfy the client methods executed.

The classes FakedWBEMConnection and DMTFCIMSchema provide the tools to build the CIM repository.

CIM namespaces are created in the CIM repository by defining a default namespace for the FakedWBEMConnection object, and by using the add_namespace() method to create additional namespaces.

There are multiple ways to add CIM objects to a target namespace of the CIM repository:

From CIM objects, using the add_cimobjects() method.

The specified CIM objects are added to or updated in a target namespace of the CIM repository. Dependent classes and qualifier types of these objects must already exist in the target namespace.
From definitions of the CIM objects in a MOF string or a MOF file, using the compile_mof_string() or compile_mof_file() methods.

The CIM objects defined in the MOF are added to or updated in a target namespace of the CIM repository. Dependent classes and qualifier types of these objects must already exist in the target namespace.
From CIM class names and a schema search path containing the MOF files of one or more schemas, using the compile_schema_classes() method.

The schema MOF files can either be provided by the user, or the DMTF CIM schema can be automatically downloaded from the DMTF using the DMTFCIMSchema() class.

The specified CIM classes are added to or updated in a target namespace of the CIM repository, and their dependent classes and qualifier types are added to the target namespace from the schemas in the search path as needed.

The dependent classes and qualifier types are determined automatically and recursively. This includes superclasses, reference classes (used in reference properties and reference parameters), and embedded classes (i.e. classes referenced through the EmbeddedInstance qualifier). Thus, a user building a CIM repository does not have to track down those dependent classes and qualifier types, and instead only needs to know the schema(s) to be used and the creation classes for any CIM instances. This also means that there is normally no reason to compile the complete schema which is much larger than the classes that are minimally needed.

It may take a combination of all of the above methods to build a CIM repository that satisfies a particular usage requirement. A typical approach for building a CIM repository is:

Establish the MOF subtrees for the schema(s) needed. That can be a downloaded version of the DMTF CIM schema, local modifications to a version of the DMTF CIM schema, user-defined schemas including schemas derived from the DMTF CIM schema, or a combination thereof.
Create the CIM namespaces needed, either as the default namespace or by adding namespaces, including the interop namespace.
For each CIM namespace needed, create the set of needed CIM classes and qualifier types by using the compile_schema_classes() method and specifying the set of creation classes of the CIM instances that are intended to be added, and specifying the pragma MOF files of the schema(s) added in step 1 as a schema search path.
For each CIM namespace needed, create the set of needed CIM instances by defining and compiling instance MOF, or by creating and adding CIMInstance objects, or both. Often defining MOF is easier for this because it simplifies the definition of association instances with the instance alias.
Register user-defined providers such as the CIMNamespaceProvider or user-written providers for the creation classes of the CIM instances that have non-default instance write behavior or that need CIM methods to be supported. See User-defined providers for details.

Example: Set up qualifier types and classes in DMTF CIM schema

This example creates a mock WBEM server using root/interop as the default namespace and compiles the classes defined in the list ‘classes’ from DMTF schema version 2.49.0 into the CIM repository along with all of the qualifier types defined by the DMTF CIM schema and any dependent classes (superclasses, etc.).

import pywbem
import pywbem_mock

conn = pywbem_mock.FakedWBEMConnection(default_namespace='root/interop')

# Leaf classes that are to be compiled along with their dependent classes
leaf_classes = ['CIM_RegisteredProfile',
                'CIM_Namespace',
                'CIM_ObjectManager',
                'CIM_ElementConformsToProfile',
                'CIM_ReferencedProfile']

# Download DMTF CIM schema version 2.49.0 into directory my_schema_dir.
schema = DMTFCIMSchema((2, 49, 0), "my_schema_dir", leaf_classes,
                       verbose=True)

# Compile the leaf classes, looking up dependent classes and qualifier
# types from the downloaded DMTF CIM schema.
conn.compile_schema_classes(leaf_classes, schema.schema_pragma_file
                            verbose=True)

# Display the resulting repository
conn.display_repository()

Example: Set up qualifier types and classes from MOF

This example creates a mock WBEM server and sets up its CIM repository with qualifier types and classes that are defined in a MOF string.

import pywbem
import pywbem_mock

tst_namespace = 'root/blah'
conn = pywbem_mock.FakedWBEMConnection()

# Add some qualifier types and classes to the CIM repo by compiling MOF
mof = '''
    Qualifier Key : boolean = false,
        Scope(property, reference),
        Flavor(DisableOverride, ToSubclass);

    Qualifier Association : boolean,
        Scope(class),
        Flavor(DisableOverride, ToSubclass);

    class TST_Class1 {
          [Key]
        string InstanceID;
        string Prop1;
    };

    class TST_Class2 {
          [Key]
        string InstanceID;
        string Prop2;
    };

      [Association]
    class TST_Association12 {
          [Key]
        TST_Class1 REF Ref1;
          [Key]
        TST_Class2 REF Ref2;
    };
'''
conn.compile_mof_string(mof, tst_namespace)

conn.display_repository()

Here is the output from displaying the CIM repository in the example above:

# ========Mock Repo Display fmt=mof namespaces=all =========


# NAMESPACE root/blah

# Namespace root/blah: contains 2 Qualifier Declarations

Qualifier Association : boolean,
    Scope(class),
    Flavor(DisableOverride, ToSubclass);

Qualifier Key : boolean = false,
    Scope(property, reference),
    Flavor(DisableOverride, ToSubclass);

# Namespace root/blah: contains 3 Classes

   [Association ( true )]
class TST_Association12 {

      [Key ( true )]
   TST_Class1 REF Ref1;

      [Key ( true )]
   TST_Class2 REF Ref2;

};

class TST_Class1 {

      [Key ( true )]
   string InstanceID;

   string Prop1;

};

class TST_Class2 {

      [Key ( true )]
   string InstanceID;

   string Prop2;

};

============End Repository=================

Example: Set up instances from single CIM objects

Based on the CIM repository content of the previous example, this example adds two class instances and one association instance from their CIM objects using the add_cimobjects() method.

c1_key = pywbem.CIMProperty('InstanceID', type='string', value='111')
c1_path = pywbem.CIMInstanceName(
    'TST_Class1',
    keybindings={c1_key.name: c1_key.value},
)
c1 = pywbem.CIMInstance(
    'TST_Class1',
    properties=[
        c1_key,
        pywbem.CIMProperty('Prop1', type='string', value='1'),
    ],
    path=c1_path,
)

c2_key = pywbem.CIMProperty('InstanceID', type='string', value='222')
c2_path = pywbem.CIMInstanceName(
    'TST_Class2',
    keybindings={c2_key.name: c2_key.value},
)
c2 = pywbem.CIMInstance(
    'TST_Class2',
    properties=[
        c2_key,
        pywbem.CIMProperty('Prop2', type='string', value='2'),
    ],
    path=c2_path,
)

a12_key1 = pywbem.CIMProperty('Ref1', type='reference', value=c1_path)
a12_key2 = pywbem.CIMProperty('Ref2', type='reference', value=c2_path)
a12_path = pywbem.CIMInstanceName(
    'TST_Association12',
    keybindings={
        a12_key1.name: a12_key1.value,
        a12_key2.name: a12_key2.value,
    },
)
a12 = pywbem.CIMInstance(
    'TST_Association12',
    properties=[
        a12_key1,
        a12_key2,
    ],
    path=a12_path,
)

conn.add_cimobjects([c1, c2, a12], tst_namespace)

conn.display_repository()

This adds the instances to the repository display of the previous example:

# Namespace root/blah: contains 3 Instances

#  Path=/root/blah:TST_Class1.InstanceID="111"
instance of TST_Class1 {
   InstanceID = "111";
   Prop1 = "1";
};

#  Path=/root/blah:TST_Class2.InstanceID="222"
instance of TST_Class2 {
   InstanceID = "222";
   Prop2 = "2";
};

#  Path=/root/blah:TST_Association12.Ref1="/:TST_Class1.InstanceID=\"111\"",Ref2="/:TST_Class2.InstanceID=\"222\""
instance of TST_Association12 {
   Ref1 = "/:TST_Class1.InstanceID=\"111\"";
   Ref2 = "/:TST_Class2.InstanceID=\"222\"";
};

DMTF CIM schema download support

A CIM schema is the collection of CIM qualifier declarations and CIM classes and available a single tested, coherent package with a defined major, minor, update version number. The DMTF regularly releases updates to the DMTF CIM schema that represent all of the classes approved by the DMTF. The MOF representation of a DMTF schema release is packaged as a single zip file and is available on the DMTF web site ( https://www.dmtf.org/standards/cim ).

Because CIM schemas are the source of most of the classes that a WBEM server normally implements it was important to create a simple mechanism to include the DMTF CIM classes and qualifier declarations from a CIM schema in the CIM repository of FakedWBEMConnection.

The DMTFCIMSchema class downloads the DMTF CIM schema zip file defined by version from the DMTF web site into a defined directory, unzips the MOF files into a subdirectory and makes this subdirectory available as a property of the DMTFCIMSchema object.

The implementation of this class depends on all of the qualiifiers and classes in the CIM schema having unique class names; this is always true for DMTF CIM schema releases to assure that they can be installed in the same namespace in a WBEM server repository.

Once aCIM schema is extracted into the individual MOF files it consumes considerable space since it expands to almost 3000 files. Therefore it is logical to remove all of the individual MOF files when not being used and also if the schema information is to be committed to be used in testing in an environment like github. Therefore, a method clean() removes all of the MOF files from local storage. They are restored the next time the DMTFCIMSchema object for the same version is constructed.

The DMTF maintains two versions of each released schema:

Final - This schema does not contain any of the schema classes that are marked experimental. It is considered the stable release.
Experimental - Contains the classes in the final schema plus other classes that are considered experimental. It is considered less stable and the experimental classes with the Experimental qualifier are subject to incompatible changes .

DMTFCIMSchema will install either the final or experimental schema depending on the value of the use_experimental parameter.

Because it is usually necessary to compile only a subset of the DMTF CIM classes into a CIM repository for any test, the DMTFCIMSchema class provides a build_schema_mof() method to create a list of MOF pragmans that includes only a subset of the classes in the downloaded CIM Schema. The task of listing classes to be compiled is futher simplified because the pywbem MOF compiler searches the DMTF schema for prerequisite classes (superclasses, reference classes, and EmbeddedInstance classes) so that generally only the leaf CIM classes required for the repository need to be in the class list. This speeds up the process of compiling DMTF CIM classes for any test significantly.

class pywbem_mock.DMTFCIMSchema(schema_version, schema_root_dir, use_experimental=False, verbose=False)[source]

DMTFCIMSchema represents a DMTF CIM Schema downloaded from the DMTF web site.

New in pywbem 0.13 as experimental and finalized in 1.2.

This class manages the download of the DMTF schema zip file and extraction of MOF files of DMTF CIM schema releases into a directory that can be used by compile_schema_classes() to compile into a CIM repository with class and qualifier declarations from the schema.

The init method downloads the schema if the schema_root_dir or the schema zip file do not exist into the directory defined by the schema_root_dir parameter and extracts the MOF files into schema_mof_dir.

If the schema zip file is already downloaded it simply sets the DMTFCIMSchema property values.

If the schema zip file was previously downloaded but schema_mof_dir does not exist the directory is created and the MOF files are extracted into this directory.

Parameters

schema_version (tuple of m, n, u) –
Represents the DMTF CIM schema version m.n.u where:
- m is the DMTF CIM schema major version
- n is the DMTF CIM schema minor version
- u is the DMTF CIM schema update version
This must represent a DMTF CIM schema that is available from the DMTF web site.
schema_root_dir (string) –
Path name of the schema root directory into which the DMTF CIM schema zip file is downloaded and in which a subdirectory for the extracted MOF files for the schema version defined is created

Multiple DMTF CIM schemas may be maintained in the same schema_root_dir simultaneously because the MOF for each schema is extracted into a subdirectory identified by the schema version information See schema_mof_dir.
use_experimental (bool) –
If True, the experimental version of the defined DMTF schema is installed.

If False, (default) the final version of the defined DMTF schema is installed.
verbose (bool) – If True, progress messages are output to stdout as the schema is downloaded and expanded. Default is False.

Raises

ValueError – if the schema cannot be retrieved from the DMTF web site.
TypeError – if the schema_version is not a valid tuple with 3 integer components

Methods:

`__repr__`()	Return a string representation of the `DMTFCIMSchema` object that is suitable for debugging.
`__str__`()	Return a short string representation of the `DMTFCIMSchema` object for human consumption.
`build_schema_mof`(class_names)	Build a string that includes the `#include pragma` statement for the CIM schema classes defined in class_names using the DMTF CIM schema defined by this instance of the class.
`clean`()	Remove all of the MOF files and the schema_mof_dir for the defined schema.
`remove`()	The schema_mof_dir directory is removed if it esists and the schema_zip_file is removed if it exists.

Attributes:

`schema_mof_dir`	Path name of the directory in which the DMTF CIM Schema MOF files are extracted from the downloaded zip file.
`schema_pragma_file`	Path name of the schema pragma file for the DMTF CIM schema.
`schema_root_dir`	Path name of the directory in which the DMTF CIM schema zip file is downloaded.
`schema_version`	The DMTF CIM schema version as a tuple of 3 integers with major version, minor version, and update version.
`schema_version_str`	The DMTF CIM schema version as a string in the form `major version>.<minor version>.<update version>`.
`schema_zip_file`	Path name of the DMTF CIM schema zip file after being downloaded from the DMTF web site.
`schema_zip_url`	URL of the DMTF CIM schema zip file that is downloaded from the DMTF web site.

__repr__()[source]: Return a string representation of the DMTFCIMSchema object that is suitable for debugging.

__str__()[source]: Return a short string representation of the DMTFCIMSchema object for human consumption. This displays the major properties of the object.

build_schema_mof(class_names)[source]

Build a string that includes the #include pragma statement for the CIM schema classes defined in class_names using the DMTF CIM schema defined by this instance of the class.

The class names in class_names can be just leaf classes within the schema . The pywbem MOF compiler will search for dependent classes including superclasses, and other classes referenced as the classes are compiled.

It builds a compilable MOF string in the form:

#pragma locale ("en_US")
#pragma include ("System/CIM_ComputerSystem.mof")
...

with a #pragma include for each class name in the class_names list.

The resulting set of #pragma statements is in the same order as the original pragmas. In some cases that could be important because the cim schema pragma file is ordered to missing dependencies and conflicts between class mof compiles

Parameters

class_names (string or list of string) –

These must be class names of classes in the DMTF CIM schema represented by this DMTFCIMSchema object. This parameter can be a string if there is only a single class name to be included.

If the returned string is compiled, the MOF compiler will search the directory defined by schema_mof_dir for classes referenced by each class in this list including super classes, classed defined by reference properties, and classes defined by an embedded-object.

Returns

Valid MOF containing pragma statements for all of the classes in schema_classes.

Return type

string

Raises

ValueError – If any of the classnames in schema_classes are not in the DMTF CIM schema installed

clean()[source]

Remove all of the MOF files and the schema_mof_dir for the defined schema. This is useful because while the downloaded schema is a single compressed zip file, it creates several thousand MOF files that take up considerable space.

The next time the DMTFCIMSchema object for this schema_version and schema_root_dir is created, the MOF file are extracted again.

remove()[source]: The schema_mof_dir directory is removed if it esists and the schema_zip_file is removed if it exists. If the schema_root_dir is empty after these removals that directory is removed.

property schema_mof_dir

Path name of the directory in which the DMTF CIM Schema MOF files are extracted from the downloaded zip file. This property can be used as the MOF compiler search path for compiling classes in the DMTF CIM schema. This directory will also contain the schema pragma file.

Type: string

property schema_pragma_file

Path name of the schema pragma file for the DMTF CIM schema. This file contains #pragama include statements for all of the classes and qualifier declarations of the schema.

The classes are represented with one file per class, and the qualifier declarations are in the files qualifiers.mof and qualifiers_optional.mof.

The path name of the schema pragma file is of the general form:

<schema_mof_dir>/cim_schema_<schema_version_str>.mof

Example:

schemas/dmtf/moffinal2490/cim_schema_2.49.0.mof

Type: string

property schema_root_dir

Path name of the directory in which the DMTF CIM schema zip file is downloaded. The MOF files are extracted into the subdirectory indicated by schema_mof_dir.

Type: string

property schema_version

The DMTF CIM schema version as a tuple of 3 integers with major version, minor version, and update version.

Example: (2, 49, 0) defines DMTF CIM schema version 2.49.0.

Type: tuple

property schema_version_str

The DMTF CIM schema version as a string in the form major version>.<minor version>.<update version>.

Example: “2.49.0” defines DMTF CIM schema version 2.49.0.

Type: string

property schema_zip_file

Path name of the DMTF CIM schema zip file after being downloaded from the DMTF web site.

Type: string

property schema_zip_url

URL of the DMTF CIM schema zip file that is downloaded from the DMTF web site.

Type: string

In-memory CIM repository classes

The class InMemoryRepository implements a CIM repository that stores the CIM objects in memory. It contains an object store (InMemoryObjectStore) for each type of CIM object (classes, instances, qualifier declarations) and for each CIM namespace in the repository. Each object store for a CIM object type contains the CIM objects of that type in a single CIM namespace.

The CIM repository of a mock WBEM server represented by a FakedWBEMConnection object is a InMemoryRepository object that is created and destroyed automatically when the FakedWBEMConnection object is created and destroyed.

The CIM repository of a mock WBEM server is accessible through its pywbem_mock.FakedWBEMConnection.cimrepository property.

class pywbem_mock.InMemoryRepository(initial_namespace=None)[source]

A CIM repository that maintains the data in memory using the methods defined in its superclass (~pywbem_mock:BaseObjectStore).

New in pywbem 1.0 as experimental and finalized in 1.2.

This implementation creates the repository as multi-level dictionary elements to define the namespaces and within each namespace the CIM classes, CIM instances, and CIM qualifiers in the repository.

Initialize an empty in-memory CIM repository and optionally add a namespace in the repository..

Parameters: initial_namespace (string or None) – Optional initial namespace that will be added to the CIM repository.

Methods:

`__repr__`()	Display summary of the repository
`add_namespace`(namespace)	Add a CIM namespace to the repository.
`get_class_store`(namespace)	Return the CIM class object store for the namespace provided.
`get_instance_store`(namespace)	Return the CIM instance object store for the namespace provided.
`get_qualifier_store`(namespace)	Return the CIM qualifier declaration object store for the namespace provided.
`load`(other)	Replace the data in this object with the data from the other object.
`print_repository`([dest])	Print the CIM repository to a destination.
`remove_namespace`(namespace)	Remove a CIM namespace from the repository.
`validate_namespace`(namespace)	Validate if the namespace exists in the repository.

Attributes:

namespaces

NocaseList of string: The names of the namespaces that exist in this CIM repository.

__repr__()[source]: Display summary of the repository

add_namespace(namespace)[source]

Add a CIM namespace to the repository.

The namespace must not yet exist in the CIM repository.

Parameters: namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.
Raises: ValueError – If the namespace argument is None or the namespace already exists.

get_class_store(namespace)[source]

Return the CIM class object store for the namespace provided.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Returns

CIM class object store for the namespace provided.

Return type

Raises

ValueError – Namespace argument is None.
KeyError – Namespace does not exist in the repository

get_instance_store(namespace)[source]

Return the CIM instance object store for the namespace provided.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Returns

CIM instance object store for the namespace provided.

Return type

Raises

ValueError – Namespace argument is None.
KeyError – Namespace argument does exist in the repository.

get_qualifier_store(namespace)[source]

Return the CIM qualifier declaration object store for the namespace provided.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Returns

CIM qualifier declaration object store for the namespace provided.

Return type

https://github.com/pywbem/pywbem

Raises

ValueError – namespace parameter is None
KeyError – namespace argument does exist in therepository.

load(other)[source]

Replace the data in this object with the data from the other object.

This is used to restore the object from a serialized state, without changing its identity.

property namespaces

NocaseList of string: The names of the namespaces that exist in this CIM repository.

Note that if there were any leading or trailing slash (“/”) characters in namespace parameters used to add the namespaces to the repository, they will be removed from the namespaces returned with this property.

print_repository(dest=None)[source]

Print the CIM repository to a destination. This displays information on the items in the data base and is only a diagnostic tool.

Parameters: dest (string) – File path of an output file. If None, the output is written to stdout.

remove_namespace(namespace)[source]

Remove a CIM namespace from the repository.

The namespace must exist in the repository and must be empty.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Raises

ValueError – Namespace argument is None or the repository namespace is not empty.
KeyError – Namespace does not exist in the CIM repository.

validate_namespace(namespace)[source]

Validate if the namespace exists in the repository. If the namespace does not exist a KeyError is raised.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Raises

KeyError – If the namespace is not defined in the repository.
ValueError – if the namespace is None.

class pywbem_mock.InMemoryObjectStore(cim_object_type)[source]

A store for CIM objects of a single type (CIM classes, CIM instances, or CIM qualifier declarations) that maintains its data in memory.

New in pywbem 1.0 as experimental and finalized in 1.2.

Instantiate the self.cim_object_type variable.

Parameters: cim_object_type (CIM object) – The Pywbem CIM object type as defined in cim_types.py for the objects in the data store. Used to verify values on create.

Methods:

`__repr__`()	Return repr(self).
`create`(name, cim_object)	Add the CIM object to the object store.
`delete`(name)	Delete the CIM object identified by name from the object store.
`get`(name[, copy])	Get with deepcopy because the pywbem .copy is only middle level and we need to completely isolate the repository.
`iter_names`()	Only copies the names for those objects that use CIMNamespaceName as the name.
`iter_values`([copy])	Return an iterator to the CIM objects in the object store.
`len`()	Return the count of objects in this object store.
`object_exists`(name)	Test if the CIM object identified by name exists in the object store.
`update`(name, cim_object)	Replace the CIM object in the object store idenfified by the name argument with the CIM object defined by the cim_object argument.

__repr__()[source]: Return repr(self).

create(name, cim_object)[source]

Add the CIM object to the object store.

Parameters

name (string or CIMInstanceName) – Name by which the CIM object will be identified in the object store.
cim_object (CIM object) – The CIM object to be added to the object store. The object is copied into the object store so the user can safely modify the original object without affecting the store.

Raises

ValueError – If CIM object already exists in the object store.

delete(name)[source]

Delete the CIM object identified by name from the object store.

Parameters: name (string or CIMInstanceName) – Name by which the object to be deleted is identified in the object store.
Raises: KeyError – If there is no object with name in this object store

get(name, copy=True)[source]: Get with deepcopy because the pywbem .copy is only middle level and we need to completely isolate the repository.

iter_names()[source]: Only copies the names for those objects that use CIMNamespaceName as the name. The others are immutable ex. classname.

iter_values(copy=True)[source]

Return an iterator to the CIM objects in the object store. This allows iteration through all the objects in this object store using iterator methods.

The order of returned CIM objects is undetermined.

Parameters: copy (bool) – Copy the objects before returning them. This is the default behavior and also the mode that should be used unless the user is certain the object will NOT be modified after it is returned.
Returns: An iterator for the objects in the object store. If copy == True, each object is copied before it is returned.
Return type: iterator

len()[source]

Return the count of objects in this object store.

Returns: Integer that is count of objects in this object store.
Return type: int

object_exists(name)[source]

Test if the CIM object identified by name exists in the object store.

Parameters: name (string or CIMInstanceName) – Name by which the object is identified in the object store.
Returns: Indicates whether the CIM object exists in the object store.
Return type: bool

update(name, cim_object)[source]

Replace the CIM object in the object store idenfified by the name argument with the CIM object defined by the cim_object argument.

Parameters

name (string or CIMInstanceName) – Name by which the object is identified in the object store.
cim_object (CIM object) – The CIM object to replace the original CIM object in the data store. The object is copied into the object store so the user can safely modify the original object without affecting the store.

Raises

KeyError – If no CIM object with name exists in the object store.

Mocking multiple CIM namespaces

The mock WBEM server allows creating multiple CIM namespaces in its CIM repository and adding CIM objects in some or all of those namespaces.

There is a default namespace created when the FakedWBEMConnection object is created from either the value of the default_namespace init parameter or its default value root/cimv2.

However, a working WBEM environment normally includes at least two namespaces:

An interop namespace which contains the parts of the model that deal with the WBEM server itself and with the implemented model (ex. CIM_Namespace, CIM_ObjectManager, CIM_RegisteredProfile, etc.) and which must be publically discoverable without the user knowing what CIM namespaces exist in the WBEM server.
A user namespace containing the CIM objects for the user model.

Pywbem_mock includes a user-defined provider for the CIM_Namespace class that can be enabled by adding code similar to the following to the setup of a mock environment:

conn = pywbem_mock.FakedWBEMConnection(...)

. . .

interop_ns = "interop"   # or "root/interop"
conn.add_namespace(interop_ns)
ns_provider = pywbem_mock.CIMNamespaceProvider(conn.cimrepository)
conn.register_provider(ns_provider, namespaces=interop_ns)

User-defined providers

Within the mock WBEM server, the response to client requests is normally determined by provider methods that use data in the CIM repository to generate responses (ex. GetInstance gets the instances from the repository, possibly filters properties and returns the instance). However, it is expected that the user may want WBEM operations on specific CIM classes to have side effects, or manage the returns differently than the normal responses.

Thus, for example, the DMTF-defined CIM_Namespace class represents the namespaces in the CIM repository. That means that its provider method for CreateInstance must create a namespace as a side effect, and that its provider methods for GetInstance or EnumerateInstances must inspect the set of namespaces in the CIM repository to generate responses, etc.

Another example of user-defined providers are classes that create their key property values automatically, for example classes that have a single InstanceID key. The provider method for CreateInstance of such classes would ignore the values for the key properties provided in the NewInstance parameter, and determine the key values on its own.

Also, the InvokeMethod operation depends on a specific provider method for the invoked CIM method in the mock WBEM server.

To meet these needs, the capability is provided to users to write user-defined providers that replace the default providers for defined classes and operations.

User-defined providers are written by implementing subclasses of specific provider classes and registering these subclasses as providers using register_provider().

The WBEM operations supported by user-defined providers can be implemented one by one. If a user-defined provider does not implement all WBEM operations, the default implementation will be used.

The following table shows the WBEM operations for which user-defined providers are supported, and the corresponding provider types:

WBEM operation	Provider type	Superclass	Provider description
CreateInstance	instance write	`InstanceWriteProvider`	User-defined instance write providers
ModifyInstance	instance write	`InstanceWriteProvider`	User-defined instance write providers
DeleteInstance	instance write	`InstanceWriteProvider`	User-defined instance write providers
InvokeMethod	method	`MethodProvider`	User-defined method providers

Creating user-defined providers

A user-defined provider can be created as follows:

Define a subclass of the superclass listed in the table above, with the methods and attributes listed below.

Example for an instance write provider:
```
from pywbem_mock import InstanceWriteProvider

class MyInstanceProvider(InstanceWriteProvider):

    . . .
```
1. Optional: It may have an __init__() method.
  
  The __init__() method takes as input parameters at least the cimrepository parameter and passes it to the superclass, and may have additional init parameters the user-defined provider requires (that are not passed on to the superclass). Additional init parameters are possible because the user creates the provider object when registering it with register_provider(). Having an __init__() method is optional if no additional init parameters are defined.
  
  Example for an __init__() method that does not define additional init parameters (and that could therefore be omitted):
```
def __init__(self, cimrepository):
    super(MyInstanceWriteProvider, self).__init__(cimrepository)
```
2. It must have a declaration of the CIM class(es) served by the provider.
  
  The CIM class or classes served by the provider are declared with a class attribute named provider_classnames. Its value must be a single string or a list/tuple of strings with the CIM class names (in any lexical case).
```
provider_classnames = 'CIM_Foo'
```
  or
```
provider_classnames = ['CIM_Foo', 'CIM_Foo_blah']
```
3. It must have an implementation of the Python methods for the WBEM operations that are overwritten by the provider.
  
  This must be all or a subset of the WBEM operations defined for the provider type. WBEM operations not implemented in the user-defined provider class default to implementations in the superclass. See Python operation methods in user-defined providers for details.
  
  Example for an CreateInstance method of an instance write provider that just calls superclass method to perform the work (and that could therefore be omitted):
```
def CreateInstance(self, namespace, NewInstance):
    return super(MyInstanceWriteProvider, self).CreateInstance(
        namespace, NewInstance)
```
4. Optional: It may define a post register setup method.
  
  The provider may override the post_register_setup() method of the provider superclass to do any special setup it needs. That method includes the current connection as a parameter so that WBEM operations on the same or on different classes can be executed. That method will be called during invocation of register_provider(), after the provider registration is successful.
  
  Example:
```
def post_register_setup(self, conn):
  # code that performs post registration setup for the provider
```
Register the user-defined provider using pywbem_mock.FakedWBEMConnection.register_provider().

This specifies the CIM namespaces for which the user-defined provider will be active. These namespaces must already exist in the CIM repository if the mock WBEM server.
```
provider = MyInstanceProvider(self.cimrepository)
conn.register_provider(provider,
                       namespaces=['root/interop', 'root/cimv2'])
```

Python operation methods in user-defined providers

The Python operation methods (i.e. the Python methods implementing WBEM operations) in user-defined providers may:

provide parameter or CIM repository validation in addition to the normal request validation,
modify parameters of the request,
abort the request with a pywbem.CIMError exception,
make modifications to the CIM repository.

The Python operation methods may call the corresponding superclass method to complete the CIM repository modification, or may implement the code to complete the modification. In any case, once a Python operation method returns, the CIM repository needs to reflect any changes on CIM objects the WBEM operation is normally expected to perform.

The Python operation methods have access to:

methods defined in the superclass of the provider, including :class:~pywbem_mock.BaseProvider`
methods to access the CIM repository using the methods defined in InMemoryRepository

The input parameters for the Python operation methods will have been already validated, including:

The input parameters have the correct Python type as per the descriptions in the superclasses.
The CIM namespace exists in the CIM repository.
The CIM class of a CIM instance or instance path specified as an input parameter exists in that namespace of the CIM repository.
The CIM properties of a CIM instance specified as an input parameter are defined in the CIM class of the instance and have the correct CIM types.
The CIM instance does not yet exist for CreateInstance and does exist for ModifyInstance.

The Python operation methods should raise any exceptions using pywbem.CIMError using the CIM status codes defined in DSP0200.

User-defined instance write providers

The InstanceWriteProvider class provides the default implementations of the CreateInstance, ModifyInstance and DeleteInstance provider methods by means of CreateInstance(), ModifyInstance(), and DeleteInstance().

A user-defined instance write provider may implement some or all of these provider methods. The method descriptions linked above provide a detailed definition of the input parameters, return values, and required behavior.

The following is a simple example of a user-defined instance write provider that serves the ‘CIM_Foo’ and ‘CIM_FooFoo’ classes and implements CreateInstance for the purpose of setting a value for the ‘InstanceID’ key property:

import uuid
from pywbem_mock import InstanceWriteProvider

class MyInstanceProvider(InstanceWriteProvider):

    # CIM classes served by this provider
    provider_classnames = ['CIM_Foo', 'CIM_FooFoo']

    def CreateInstance(self, namespace, new_instance):
        new_instance.properties["InstanceID"] = \
            "{}.{}".format(new_instance.classname, uuid.uuid4())
        return super(MyInstanceProvider, self).CreateInstance(
            namespace, new_instance)

Because the provider in this example does not implement the ModifyInstance and DeleteInstance methods, these operations will use their default implementations from InstanceWriteProvider.

The provider in this example does not need to implement an __init__() method, because no additional init parameters are needed.

class pywbem_mock.InstanceWriteProvider(cimrepository=None)[source]

This class defines those instance provider methods that may have user- defined providers that override the default provider implementation in this class.

New in pywbem 1.0 as experimental and finalized in 1.2.

User providers are defined by creating a subclass of this class and defining a new provider method for one of the methods in this class with the same signature.

Note that user-defined providers may, in turn, call the default providers in this class.

Parameters: cimrepository (BaseRepository or subclass) – The CIM repository to be used by the provider.

Methods:

`CreateInstance`(namespace, new_instance)	Default provider method for `pywbem.WBEMConnection.CreateInstance()`.
`DeleteInstance`(InstanceName)	Default provider method for `pywbem.WBEMConnection.DeleteInstance()`.
`ModifyInstance`(modified_instance[, ...])	Default provider method for `pywbem.WBEMConnection.CreateInstance()`.
`__repr__`()	Return repr(self).
`add_namespace`(namespace[, verbose])	Add a CIM namespace to the CIM repository.
`class_exists`(namespace, classname)	Test if class defined by classname parameter exists in CIM repository defined by namespace parameter.
`filter_properties`(obj, property_list)	Remove properties from an instance or class that aren't in the property_list parameter.
`find_interop_namespace`()	Find the Interop namespace name in the CIM repository, or return None.
`get_class`(namespace, classname[, ...])	Get class from CIM repository.
`is_interop_namespace`(namespace)	Tests if a namespace name is a valid Interop namespace name.
`is_subclass`(klass, superclass, class_store)	Return boolean indicating whether a class is a (direct or indirect) subclass of a superclass, or the same class, in the specified class store of the CIM repository (i.e.
`post_register_setup`(conn)	Method called by provider registration after registation of provider is successful.
`remove_namespace`(namespace[, verbose])	Remove a CIM namespace from the CIM repository.
`validate_namespace`(namespace)	Validates that a namespace is defined in the CIM repository.

Attributes:

`cimrepository`	Instance of class that represents the CIM repository.
`interop_namespace_names`	NocaseList of string: The valid Interop namespace names.
`namespaces`	NocaseList of string: The names of the namespaces that exist in the CIM repository.
`provider_type`	Keyword defining the type of request the provider will service.

CreateInstance(namespace, new_instance)[source]

Default provider method for pywbem.WBEMConnection.CreateInstance().

Create a new CIM instance in the CIM repository of the mock WBEM server.

Validation already performed by the provider dispatcher that calls this provider method:

The provider method is called only for the registered class and namespace (only applies to user-defined providers).
The Python types of all input parameters to this provider method are as specified below.
The namespace exists in the CIM repository.
The creation class of the new instance exists in the namespace in the CIM repository.
All properties specified in the new instance are exposed (i.e. defined and inherited with any overrides resolved) by the creation class in the CIM repository, and have the same type-related attributes (i.e. type, is_array, embedded_object).
The creation class of the new instance must not be an abstract class.

Validation that should be performed by this provider method:

new_instance does not specify any properties that are not allowed to be initialized by the client, depending on the model implemented by the provider.
new_instance specifies all key properties needed by the provider, depending on the model implemented by the provider. The CIM repository will reject any new instance that does not have all key properties specified.
The new instance (i.e. an instance with the new instance path) does not exist in the CIM repository. This validation needs to be done by the provider because the determination of the key properties for the new instance path may depend on the model implemented by the provider. The CIM repository will reject the creation of instances that already exist, so this check can be delegated to the repository once the new instance path has been determined.

Parameters

namespace (string) – The name of the CIM namespace in which the CIM instance is to be created, in any lexical case, and with leading and trailing slash characters removed.
new_instance (CIMInstance) –
A representation of the CIM instance to be created.

This object is a deep copy of the original client parameter, and may be modified by the provider as needed, before storing it in the CIM repository.

The property names in this object have been adjusted to match the lexical case of the property definitions in the creation class of the instance in the CIM repository.

The classname attribute of this object will specify the creation class for the new instance, in any lexical case.

The properties attribute of this object will specify the initial property values for the new CIM instance, with property names in any lexical case. Key properties may or may not be included.

The path attribute of this object will be None.

The qualifiers attribute of this object, if non-empty, should be ignored by the provider, because instance-level qualifiers have been deprecated in CIM.

Returns

Instance path of the new CIM instance.

Return type

CIMInstanceName

Raises

CIMError – The provider may raise CIMError with any status code, and typically raises: - CIM_ERR_INVALID_PARAMETER - CIM_ERR_ALREADY_EXISTS

DeleteInstance(InstanceName)[source]

Default provider method for pywbem.WBEMConnection.DeleteInstance().

Delete an existing instance in the CIM repository of the mock WBEM server.

NOTE: This method specifies the namespace in InstanceName rather than as a separate input parameter.

The provider is not responsible for determining other instances that depend on the instance to be deleted (e.g. association instances referencing the instance to be deleted); such dependency detection and handling is done elsewhere.

Validation already performed by the provider dispatcher that calls this provider method:

The provider method is called only for the registered class and namespace (only applies to user-defined providers).
The Python types of all input parameters to this provider method are as specified below.
The namespace exists in the CIM repository.
The creation class of the instance to be deleted exists in the namespace of the CIM repository.
The instance to be deleted exists in the namespace of the CIM repository.

Parameters

InstanceName (CIMInstanceName) –

The instance path of the instance to be deleted with the following attributes:

classname: Name of the creation class of the instance.
keybindings: Keybindings of the instance.
namespace: Name of the CIM namespace containing the instance. Will not be None.
host: Will be None.

ModifyInstance(modified_instance, IncludeQualifiers=None)[source]

Default provider method for pywbem.WBEMConnection.CreateInstance().

Modify an existing CIM instance in the CIM repository of the mock WBEM server.

NOTE: This method specifies the namespace in modified_instance.path rather than as a separate input parameter.

The modification of the instance in the CIM repository that is performed by the provider should be limited to property value changes (including addition of properties if not yet set on the instance), because instance-level qualifiers have been deprecated in CIM.

The set of properties that are to be modified in the CIM instance has already been determined by the caller so that the modified_instance parameter specifies exactly the set of properties to be modified. Therefore, this provider method does not have a property list parameter.

Validation already performed by the provider dispatcher that calls this provider method:

The provider method is called only for the registered class and namespace (only applies to user-defined providers).
The Python types of all input parameters to this provider method are as specified below.
The classnames in modified_instance are consistent between instance and instance path.
The namespace exists in the CIM repository.
The creation class of the instance to be modified exists in the namespace of the CIM repository.
The instance to be modified exists in the namespace of the CIM repository.
All properties in modified_instance that are to be modified are exposed (i.e. defined and inherited with any overrides resolved) by the creation class in the CIM repository, and have the same type-related attributes (i.e. type, is_array, embedded_object).
No key properties are requested to change their values.

Validation that should be performed by this provider method:

modified_instance does not specify any changed values for properties that are not allowed to be changed by the client, depending on the model implemented by the provider.

Parameters

modified_instance (CIMInstance) –
A representation of the modified CIM instance, also indicating its instance path, with exactly the set of properties to be modified.

This object is a deep copy of the original client parameter, and may be modified by the provider as needed, before storing it in the CIM repository.

The path attribute of this object will be set and is the instance path of the instance to be modified in the CIM repository. Its namespace, classname and keybindings attributes will be set. The names will be in any lexical case.

The classname attribute of this object will specify the creation class of the instance to be modified, in any lexical case.

The properties attribute of this object will specify exactly the set of properties that are to be updated, taking into account the original ModifiedInstance and PropertyList input parameters of the ModifyInstance() client call. The lexical case of the property names has been adjusted to match the lexical cae of the property definitions in the creation class in the CIM repository.

The qualifiers attribute of this object, if non-empty, should be ignored by the provider, because instance-level qualifiers have been deprecated in CIM.
IncludeQualifiers (bool) – This parameter should be ignored by the provider, because instance-level qualifiers have been deprecated in CIM.

Raises

CIMError – The provider may raise CIMError with any status code, and typically raises: - CIM_ERR_INVALID_PARAMETER

post_register_setup(conn)[source]

Method called by provider registration after registation of provider is successful. Using this method is optional for registration cases where the provider must execute some activity (ex. modify the CIM repository after successful provider registration).

Override this method in the user-defined provider subclass to execute this method.

Parameters: conn (WBEMConnection) – Current connection which allows client methods to be executed from within this method.

provider_type = 'instance-write'

Keyword defining the type of request the provider will service. The type for this provider class is predefined as ‘instance’.

Type: string

User-defined method providers

The MethodProvider class provides the default implementation of the InvokeMethod provider method by means of InvokeMethod().

The default implementation raises CIMError with CIM_ERR_METHOD_NOT_AVAILABLE, because there is no meaningful default implementation of CIM methods. A user-defined method provider implements this provider method. The method description linked above provides a detailed definition of the input parameters, return values, and required behavior.

The following example implements method Method1 defined in class CIM_Foo_sub_sub that is defined as follows:

    [Description ("Subclass of CIM_Foo_sub")]
class CIM_Foo_sub_sub : CIM_Foo_sub {

    string cimfoo_sub_sub;

        [Description("Sample method with input and output parameters")]
    uint32 Method1(
        [IN ( false), OUT, Description("Response param 2")]
      string OutputParam2);
};

The example implementation of method Method1 in the user-defined method provider modifies the value of property cimfoo_sub_sub of the instance, and returns it as its output parameter OutputParam2:

from pywbem import CIMInstanceName, CIMError, \
    CIM_ERR_INVALID_PARAMETER, CIM_ERR_METHOD_NOT_AVAILABLE
from pywbem_mock import MethodProvider

class MyMethodProvider(MethodProvider):

    provider_classnames = 'CIM_Foo_sub_sub'

    def InvokeMethod(self, methodname, localobject, params):

        if methodname.lower() == 'method1':
            if isinstance(localobject, CIMClassName):
                raise CIMError(
                    CIM_ERR_INVALID_PARAMETER,
                    "CIM method {0} must be invoked on a CIM instance".
                    format(methodname))
            return self.Method1(localobject, params)
        else:
            raise CIMError(CIM_ERR_METHOD_NOT_AVAILABLE)

    def Method1(self, localobject, params):
        '''
        Implementation of CIM method 'Method1'.
        '''
        namespace = localobject.namespace
        instance_store = self.cimrepository.get_instance_store(namespace)

        # Get the instance the method was invoked on, from the CIM
        # repository (as a copy)
        instance = instance_store.get(localobject.path)  # a copy

        # Modify a property value in the local copy of the instance
        if 'cimfoo_sub_sub' not in instance.properties:
            instance.properties['cimfoo_sub_sub'] = 'new'
        instance.properties['cimfoo_sub_sub'] += '+'

        # Update the instance in the CIM repository from the changed
        # local instance
        instance_store.update(localobject.path, instance)

        # Return the property value in the output parameter
        outputparam2 = instance.properties['cimfoo_sub_sub']
        out_params = [
            CIMParameter('OutputParam2', type='string', value=outputparam2),
        ]

        # Set the return value of the CIM method
        return_value = 0

        return (return_value, out_params)

class pywbem_mock.MethodProvider(cimrepository=None)[source]

This class defines the provider class that handles the default InvokeMethod.

New in pywbem 1.0 as experimental and finalized in 1.2.

User method providers are defined by creating a subclass of this class and defining an InvokeMethod based on the method in this class.

Parameters: cimrepository (BaseRepository or subclass) – Defines the repository to be used by the provider.

Methods:

`InvokeMethod`(methodname, localobject, params)	Default provider method for `pywbem.WBEMConnection.InvokeMethod()`.
`__repr__`()	Return repr(self).
`add_namespace`(namespace[, verbose])	Add a CIM namespace to the CIM repository.
`class_exists`(namespace, classname)	Test if class defined by classname parameter exists in CIM repository defined by namespace parameter.
`filter_properties`(obj, property_list)	Remove properties from an instance or class that aren't in the property_list parameter.
`find_interop_namespace`()	Find the Interop namespace name in the CIM repository, or return None.
`get_class`(namespace, classname[, ...])	Get class from CIM repository.
`is_interop_namespace`(namespace)	Tests if a namespace name is a valid Interop namespace name.
`is_subclass`(klass, superclass, class_store)	Return boolean indicating whether a class is a (direct or indirect) subclass of a superclass, or the same class, in the specified class store of the CIM repository (i.e.
`post_register_setup`(conn)	Method called by provider registration after registation of provider is successful.
`remove_namespace`(namespace[, verbose])	Remove a CIM namespace from the CIM repository.
`validate_namespace`(namespace)	Validates that a namespace is defined in the CIM repository.

Attributes:

`cimrepository`	Instance of class that represents the CIM repository.
`interop_namespace_names`	NocaseList of string: The valid Interop namespace names.
`namespaces`	NocaseList of string: The names of the namespaces that exist in the CIM repository.
`provider_type`	provider_type (string): Keyword defining the type of request the provider will service.

InvokeMethod(methodname, localobject, params)[source]

Default provider method for pywbem.WBEMConnection.InvokeMethod().

Invoke a CIM method (static or dynamic) on a target CIM object (class or instance) in the CIM repository of the mock WBEM server.

This default provider always raises CIMError(CIM_ERR_METHOD_NOT_FOUND) because there is no concept of a default method invocation behavior in in CIM (other than raising this error). A user-defined method provider is necessary to have a meaningful implementation of a method invocation.

Validation already performed by the provider dispatcher that calls this provider method:

The provider method is called only for the registered class and namespace (only applies to user-defined providers).
The Python types of all input parameters to this provider method are as specified below.
The namespace exists in the CIM repository.
For instance-level use:
- The creation class of the target instance exists in the namespace of the CIM repository.
- The target instance exists in the namespace of the CIM repository.
- The creation class of the target instance exposes the method to be invoked.
For class-level use:
- The target class exists in the namespace of the CIM repository.
- The target class exposes the method to be invoked.
- The method exposed by the creation class is a static method as per its ‘Static’ qualifier.
The set of specified CIM method input parameters matches exactly the set of input parameters defined by the method in the CIM repository (as detected by their ‘In’ qualifier in the creation class), w.r.t. parameter name and type-related attributes (type, is_array, embedded_object).

Validation that should be performed by this provider method:

MethodName is the name of a method the provider implements.
Constraints on the values of input parameters.

Parameters

methodname (string) – Name of the CIM method to be invoked, in any lexical case.
objectname –
(CIMInstanceName or CIMClassName): A reference to the target CIM object, as follows:
- For instance-level use: The instance path of the target instance, as a CIMInstanceName object, with the following attributes:
  - classname: Will be set, in any lexical case.
  - keybindings: Will be set, with key names in any lexical case.
  - namespace: Will be set, in any lexical case, and with leading and trailing slash characters removed.
  - host: Will be None.
- For class-level use: The class path of the target class, as a CIMClassName object, with the following attributes:
  - classname: Will be set, in any lexical case.
  - namespace: Will be set, in any lexical case, and with leading and trailing slash characters removed.
  - host: Will be None.
params (pywbem.NocaseDict) –
The input parameters for the method invocation, as a pywbem.NocaseDict object, with items as follows:
- key (string): The parameter name, in any lexical case.
- value (CIMParameter): The parameter value.

Returns

The return value and output parameters of the method invocation:

return_value (CIM data type): Return value of the method invocation.
out_params (Sequence or Mapping): Output parameters of the method invocation.

If Sequence, the items must be CIMParameter in any order, with these attributes set:
- name (string): Parameter name
- value (CIM data type): Parameter value
If Mapping, the items must be as follows:
- key (string): Parameter name
- value (CIM data type or CIMParameter): Parameter value

Return type

tuple (return_value, out_params)

Raises

CIMError – (CIM_ERR_METHOD_NOT_FOUND) because the default method is only a placeholder for the API and documentation and not a real InvokeMethod action implementation.

post_register_setup(conn)[source]

Method called by provider registration after registation of provider is successful. Using this method is optional for registration cases where the provider must execute some activity (ex. modify the CIM repository after successful provider registration).

Override this method in the user-defined provider subclass to execute this method.

Parameters: conn (WBEMConnection) – Current connection which allows client methods to be executed from within this method.

provider_type = 'method': provider_type (string): Keyword defining the type of request the provider will service. The type for this class is predefined as ‘method’

CIM_Namespace provider

This module implements a user-defined provider for the class CIM_Namespace

This provider manages creation and deletion of the instances of the CIM_Namespace class and limits that activity to the server environment interop classname. The CIM_Namespace class is a DMTF defined class that defines an instance for each namespace in the server environment and allows the creation and deletion of server CIM namespaces to be controlled through creation and deletion of instances of the CIM_Namespace class.

class pywbem_mock.CIMNamespaceProvider(cimrepository)[source]

Implements the user defined provider for the class CIM_Namespace.

This provider provides the create, modify, and delete methods for adding an instance of the class CIM_Namspace when a namespace is created or deleted in a pywbem mock environment.

This class and the instances of this class only exist in the WBEM server Interop namespace per DMTF definitions.

This class __init__ saves the cimrepository variable used by methods in this class and by methods of its superclasses (i.e. InstanceWriteProvider).

The provider defines the class level attribute provider_classnames (CIM_Namespace)

This provider presumes that an Interop namespace has been created before the provider object is constructed and fails the constructor if there is not interop_namespace

Parameters: cimrepository (BaseRepository or subclass) – Defines the CIM repository to be used by the provider.

Methods:

`CreateInstance`(namespace, new_instance)	Create an instance of the CIM_Namespace class in an Interop namespace of the CIM repository, and if not yet existing create the new namespace in the CIM repository.
`DeleteInstance`(InstanceName)	Delete an instance of the CIM_Namespace class in an Interop namespace of the CIM repository, and in addition delete the namespace represented by it in the CIM repository.
`ModifyInstance`(modified_instance[, ...])	Modification of CIM_Namespace instance not allowed
`__repr__`()	Return repr(self).
`add_namespace`(namespace[, verbose])	Add a CIM namespace to the CIM repository.
`class_exists`(namespace, classname)	Test if class defined by classname parameter exists in CIM repository defined by namespace parameter.
`create_cimnamespace_instance`(conn, ...)	Build and execute CreateInstance for an instance of CIM_Namespace using the namespace parameter as the value of the name property in the instance.
`filter_properties`(obj, property_list)	Remove properties from an instance or class that aren't in the property_list parameter.
`find_interop_namespace`()	Find the Interop namespace name in the CIM repository, or return None.
`get_class`(namespace, classname[, ...])	Get class from CIM repository.
`is_interop_namespace`(namespace)	Tests if a namespace name is a valid Interop namespace name.
`is_subclass`(klass, superclass, class_store)	Return boolean indicating whether a class is a (direct or indirect) subclass of a superclass, or the same class, in the specified class store of the CIM repository (i.e.
`post_register_setup`(conn)	Method called by FakedWBEMConnection.register_provider to complete initialization of this provider.
`remove_namespace`(namespace[, verbose])	Remove a CIM namespace from the CIM repository.
`validate_namespace`(namespace)	Validates that a namespace is defined in the CIM repository.

Attributes:

`cimrepository`	Instance of class that represents the CIM repository.
`interop_namespace_names`	NocaseList of string: The valid Interop namespace names.
`namespaces`	NocaseList of string: The names of the namespaces that exist in the CIM repository.
`provider_classnames`	provider_classnames (string): The classname for this provider

CreateInstance(namespace, new_instance)[source]

Create an instance of the CIM_Namespace class in an Interop namespace of the CIM repository, and if not yet existing create the new namespace in the CIM repository.

See ~pywbem_mock.InstanceWriteProvider.CreateInstance for documentation of validation and description of input parameters, noting extra conditions for this provider as described below:

Parameters

namespace (string) – Must be a valid Interop namespace.
new_instance (CIMInstance) –
The following applies regarding its properties:
- ’Name’ property: This property is required since it defines the name of the new namespace to be created.
- ’CreationClassName’ property: This property is required and its value must match the class name of the new instance.

Raises

CIMError – (CIM_ERR_INVALID_PARAMETER) if namespace is not the Interop namespace in the CIM repository or the Name property does not exist or the other properties cannot be added to the instance.

DeleteInstance(InstanceName)[source]

Delete an instance of the CIM_Namespace class in an Interop namespace of the CIM repository, and in addition delete the namespace represented by it in the CIM repository.

See ~pywbem_mock.InstanceWriteProvider.CreateInstance for documentation of validation and description of input parameters, noting extra conditions for this provider as described below:

The namespace to be deleted must be empty and must not be the Interop namespace.

Parameters

InstanceName – (CIMInstanceName): The keybinding Name must exist; it defines the namespace to be deleted.

Raises

CIMError – (CIM_ERR_INVALID_PARAMETER)
CIMError – (CIM_ERR_NAMESPACE_NOT_EMPTY)

ModifyInstance(modified_instance, IncludeQualifiers=None)[source]: Modification of CIM_Namespace instance not allowed

__repr__()[source]: Return repr(self).

static create_cimnamespace_instance(conn, namespace, interop_namespace, klass)[source]

Build and execute CreateInstance for an instance of CIM_Namespace using the namespace parameter as the value of the name property in the instance. The instance is created in the interop_namespace

Parameters

namespace (string) – Namespace that this instance defines.
interop_namespace (string) – Interop namespace for this environment.
klass (CIMClass) – The CIM class CIM_Namespace which is used to create the instance.

Raises

CIMError – For errors encountered with CreateInstance

post_register_setup(conn)[source]

Method called by FakedWBEMConnection.register_provider to complete initialization of this provider. This method is called after the required classes are installed in the cim_repository

This is necessary because pywbem_mock does not allow user-defined providers for the instance read operations such as EnumerateInstances so the instance for each namespace must be exist in the repository.

This method:

Inserts instances of CIM_Namespace for every namespace in the CIM repository.

provider_classnames = 'CIM_Namespace': provider_classnames (string): The classname for this provider

Registry for provider dependent files

A faked WBEM connection provides a registry for provider dependent files in its provider_dependent_registry property of type pywbem_mock.ProviderDependentRegistry.

This registry can be used by callers to register and look up the path names of additional dependent files of a mock script, in context of that mock script.

The pywbemtools project makes use of this registry for validating whether its mock cache is up to date w.r.t. additional dependent files a mock script has used.

class pywbem_mock.ProviderDependentRegistry[source]

A registry for provider dependent files in context of a mock script.

New in pywbem 1.1 as experimental and finalized in 1.2.

This registry allows registering additional dependent files in context of a mock script, and to look them up again.

The registry works with the path names of the mock script and dependent files and normalizes these path names as follows:

The path is relative to the user’s home directory, if possible. If not possible (i.e. on Windows when on a different drive than the home directory), the path is absolute.
The path does not contain redundant path separators or same-level or up-level directories.
On case insensitive file systems, the lexical case is normalized to lower case.
The native path seprarators of the operating system are used.

Methods:

`__repr__`()	Return repr(self).
`add_dependents`(mock_script_path, dependent_paths)	Add dependent files to the registry, in context of a mock script.
`iter_dependents`(mock_script_path)	Iterate through the path names of the dependent files that are registered for a mock script.
`load`(other)	Replace the data in this object with the data from the other object.

__repr__()[source]: Return repr(self).

add_dependents(mock_script_path, dependent_paths)[source]

Add dependent files to the registry, in context of a mock script.

Parameters

mock_script_path (string) – Path name of the mock script. May be relative or absolute, and will be normalized to look up the registered dependents.
dependent_paths (string or list of string) – Path name(s) of provider dependent files to be registered. May be relative or absolute, and will be normalized when registering them.

iter_dependents(mock_script_path)[source]

Iterate through the path names of the dependent files that are registered for a mock script.

If the mock script is not registered, the iteration is empty.

The iterated path names are the normalized path names, but with a path that makes them accessible from within the current directory.

Parameters: mock_script_path (string) – Path name of the mock script. May be relative or absolute, and will be normalized to look up the registered dependents.
Returns: A generator iterator for the path names of the dependent files.
Return type: iterator

load(other)[source]

Replace the data in this object with the data from the other object.

This is used to restore the object from a serialized state, without changing its identity.

Configuration of mocked behavior

Pywbem_mock supports several variables that provide configuration and behavior control of the mock environment.

These configuration variables can be modified by the user directly after importing pywbem. For example:

import pywbem_mock
pywbem_mock.config.SYSTEMNAME = 'MyTestSystemName'

Note that the pywbem source file defining these variables should not be changed by the user. Instead, the technique shown in the example above should be used to modify the configuration variables.

pywbem_mock.config.DEFAULT_MAX_OBJECT_COUNT = 100: Default value for the MaxObjectCount parameter of the Open…() methods of the mock WBEM server, if the value was not provided by the user.

pywbem_mock.config.IGNORE_INSTANCE_ICO_PARAM = True

Use of the IncludeClassOrigin parameter on instance requests is DEPRECATED. A WBEM server may choose to treat the value of IncludeClassOrigin parameter as false for all requests, otherwise the implementation shall support the original behavior as defined in the rest of this paragraph. If the IncludeClassOrigin input parameter is true, the CLASSORIGIN attribute shall be present on all appropriate elements in each returned Instance. If it is false, no CLASSORIGIN attributes are present.

The following variable forces pywbem_mock to ignore the client supplied variable and not return qualifiers on EnumerateInstances and GetInstance responses.

True (default): pywbem_mock always removes class origin attributes from instances in responses
False: pywbem_mock uses value of input parameter or its default to determine if class origin attributes are to be removed

pywbem_mock.config.IGNORE_INSTANCE_IQ_PARAM = True

Use of the IncludeQualifiers parameter on instance requests is DEPRECATED in DMTF DSP0200. The definition of IncludeQualifiers is ambiguous and when this parameter is set to true, WBEM clients cannot be assured that any qualifiers will be returned. A WBEM client should always set this parameter to false. To minimize the impact of this recommendation on WBEM clients, a WBEM server may choose to treat the value of IncludeQualifiers as false for all requests.

The following variable forces pywbem_mock to ignore the client supplied variable and not return qualifiers on EnumerateInstances and GetInstance responses.

True (default): pywbem_mock always removes qualifiers from instances in responses
False: pywbem_mock uses value of input parameter or its default to determine if qualifiers are to be removed

pywbem_mock.config.OBJECTMANAGERCREATIONCLASSNAME = 'CIM_ObjectManager': Value for the CIM_ObjectManagerCreationClassName defined in the CIM_ObjectManager class.

pywbem_mock.config.OBJECTMANAGERNAME = 'FakeObjectManager': Name for the object manager It is used in defining user-defined provider properties for CIM_Namespace provider and CIM_ObjectManager provider if if they are defined.

pywbem_mock.config.OPEN_MAX_TIMEOUT = 40: Maximum value for the OperationTimeout parameter of the Open…() methods of the mock WBEM server.

pywbem_mock.config.SYSTEMCREATIONCLASSNAME = 'CIM_ComputerSystem': Name for the property SystemCreationClassname defined a number of CIM classes that are used by the pywbem_mock including CIM_Namespace

pywbem_mock.config.SYSTEMNAME = 'MockSystem_WBEMServerTest': The name of the mock object. This string value becomes part of the CIM_ObjectNamager instance and CIM_Namespace instances

WBEM utility commands

The pywbem package provides a number of WBEM utility commands. They are all implemented as pure-Python scripts.

These commands are installed into the Python script directory and should therefore automatically be available in the command search path.

The following commands are provided:

mof_compiler

A MOF compiler that takes MOF files as input and updates the CIM repository of a WBEM server with the result.

Versions of pywbem before 1.0.0 provided a command wbemcli as an interactive command line environment. It is recommended to use the pywbemcli command from the pywbemtools package on Pypi as a replacement.

mof_compiler

The mof_compiler command compiles MOF files and updates the CIM repository of a WBEM server with the result.

If the compiler fails, any changes made to the CIM repository in the WBEM server as part of the current compilation are rolled back. A limitation is that changes to qualifier declarations are not yet rolled back (see issue #990).

The compiler provides a dry-run mode that simulates the compilation but does not change the CIM repository in the WBEM server.

Here is the help text of the command:

usage: mof_compiler [options] moffile ...

Compile MOF files, and update a namespace in a WBEM server with the result.

Positional arguments:
  moffile               Path name of the MOF file to be compiled.
                        Can be specified multiple times.

Server related options:
  Specify the WBEM server and namespace the MOF compiler works against.

  -s url, --server url  Host name or URL of the WBEM server (required),
                        in this format:
                            [scheme://]host[:port]
                        - scheme: Defines the protocol to use:
                            - "https" for HTTPS protocol
                            - "http" for HTTP protocol
                          Default: "https".
                        - host: Defines host name as follows:
                             - short or fully qualified DNS hostname
                             - literal IPV4 address(dotted)
                             - literal IPV6 address (RFC 3986) with zone
                               identifier extensions(RFC 6874)
                               supporting "-" or %25 for the delimiter
                        - port: Defines the WBEM server port to be used.
                          Defaults:
                             - 5988, when using HTTP
                             - 5989, whenusing HTTPS
  -n namespace, --namespace namespace
                        Namespace in the WBEM server.
                        Default: root/cimv2

Connection security related options:
  Specify user name and password or certificates and keys.

  -u user, --user user  User name for authenticating with the WBEM server.
                        Default: No user name.
  -p password, --password password
                        Password for authenticating with the WBEM server.
                        Default: Will be prompted for, if user name specified.
  -nvc, --no-verify-cert
                        Client will not verify certificate returned by the WBEM
                        server (see cacerts). This bypasses the client-side
                        verification of the server identity, but allows encrypted
                        communication with a server for which the client does not have
                        certificates.
  --cacerts cacerts     CA certificates to be used for verifying the server
                        certificate presented by the WBEM server during TLS/SSL
                        handshake:
                        FILE: Use the certs in the specified cert file;
                        DIR: Use the certs in the specified cert directory.
                        Default: Use certs from the certifi Python package.
  --certfile certfile   Client certificate file for authenticating with the
                        WBEM server. If option specified the client attempts
                        to execute mutual authentication.
                        Default: Simple authentication.
  --keyfile keyfile     Client private key file for authenticating with the
                        WBEM server. Not required if private key is part of the
                        certfile option. Not allowed if no certfile option.
                        Default: No client key file. Client private key should
                        then be part of the certfile.

Action related options:
  Specify actions against the WBEM server's namespace.

  -r, --remove          Removal mode: Remove elements (found in the MOF files) from
                        the WBEM server's namespace, instead of creating or updating
                        them.
  -d, --dry-run         Dry-run mode: Don't actually modify the WBEM server's
                        namespace, just check MOF syntax. Connection to WBEM server is
                        still required to check qualifiers.

General options:
  -I dir, --include dir
                        Path name of a MOF include directory. Can be specified
                        multiple times.
  -v, --verbose         Print more messages while processing
  -V, --version         Display pywbem version and exit.
  -h, --help            Show this help message and exit
  --log log_spec[,logspec]
                        Log_spec defines characteristics of the various named
                        loggers. It is the form:
                         COMP=[DEST[:DETAIL]] where:
                           COMP:   Logger component name:[api|http|all].
                                   (Default=all)
                           DEST:   Destination for component:[file|stderr|off].
                                   (Default=file)
                           DETAIL: Detail Level to log: [all|paths|summary] or
                                   an integer that defines the maximum length of
                                   of each log record.
                                   (Default=all)

Example: mof_compiler CIM_Schema_2.45.mof -s https://localhost -n root/cimv2
-u sheldon -p p42

Development

This section only needs to be read by developers of the pywbem package. People that want to make a fix or develop some extension, and people that want to test the project are also considered developers for the purpose of this section.

Repository

The repository for pywbem is on GitHub:

Setting up the development environment

You may use any supported OS platform as the development environment for pywbem. On native Windows, you need to use a Windows command prompt in administrator mode.

It is recommended that you set up a virtual Python environment. Have the virtual Python environment active for all remaining steps.
Make sure the following commands are available:
- git
- make (GNU make)
- choco on native Windows (Chocolatey package manager)
Clone the Git repo of this project and switch to its working directory:
```
$ git clone git@github.com:pywbem/pywbem.git
$ cd pywbem
```
Install the prerequsites for pywbem development. This will install Python packages into the active Python environment, and OS-level packages:
```
$ make develop
```
On Python 3.4 on native Windows, this may fail during installation of the lxml Python package. If so, see Troubleshooting for details.
This project uses Make to do things in the currently active Python environment. The command:
```
$ make
```
displays a list of valid Make targets and a short description of what each target does. See the next sections for details.

Building the documentation

The ReadTheDocs (RTD) site is used to publish the documentation for the pywbem package at https://pywbem.readthedocs.io/

This page is automatically updated whenever the Git repo for this package changes the branch from which this documentation is built.

In order to build the documentation locally from the Git work directory, execute:

$ make builddoc

The top-level document to open with a web browser will be build_doc/html/docs/index.html.

Testing

All of the following make commands run the tests in the currently active Python environment, and need to be invoked in the Git repo work directory.

By default, the tests use the pywbem and pywbem_mock modules from the respective directories in the Git repo work directory. Pywbem 0.14.5 introduced a way to test installed versions of the pywbem package. For details, see Testing installed versions of pywbem.

The tests directory has the following subdirectory structure:

tests
 +-- unittest            Unit tests
 |    +-- utils               Utility functions used by unit tests
 |    +-- pywbem              Unit tests for the pywbem package
 |    +-- pywbem_mock         Unit tests for the pywbem_mock package
 |    +-- unittest_utils      Unit tests for tests/unittest/utils
 |    +-- functiontest        Unit tests for tests/functiontest
 |    +-- end2endtest_utils   Unit tests for tests/end2endtest/utils
 |    +-- servers             Unit tests for tests/servers
 +-- functiontest        Function tests
 +-- end2endtest         End2end tests
 |    +-- utils               Utility functions used by end2end tests
 +-- manualtest          Manual tests
 +-- server_definitions  WBEM server definition file used by some tests and module
 |                         for accessing it
 +-- profiles            Simple definitions of management profiles used by some tests
 +-- schema              The CIM schema MOF files used by some MOF tests
 +-- dtd                 The CIM DTD file used by some CIM-XML validation tests

There are multiple types of tests in pywbem:

Unit tests and function tests

These tests do not require any WBEM server to be available, and the tests validate their results automatically.

The distinction between unit tests and function tests as used in pywbem is that function tests exercise the entire pywbem client component or entire pywbem scripts, while unit tests exercise single modules.

They are run by executing:
```
$ make test
```
Test execution can be modified by a number of environment variables, as documented in the make help (execute make help).

An alternative that does not depend on the makefile and thus can be executed from the source distribution archive, is:
```
$ ./setup.py test
```
Options for pytest can be passed using the --pytest-options option.
End2end tests

These tests are run against one or more WBEM servers, and the tests validate their results automatically.

They are run by preparing a server definition file:
```
tests/server_definitions/server_definition_file.yml
```
from the provided example, and by executing:
```
$ make end2endtest
```
Again, test execution can be modified by a number of environment variables, as documented in the make help (execute make help).

An alternative that does not depend on the makefile, is:
```
$ ./setup.py end2endtest
```
Options for pytest can be passed using the --pytest-options option.
Manual tests

There are several Python scripts and shell scripts that can be run manually. The results need to be validated manually.

These scripts are in the directory:
```
tests/manualtest/
```
and are executed by simply invoking them from within the main directory of the repository, e.g.:
```
tests/manualtest/run_cim_operations.py
```
Some of the scripts support a –help option that informs about their usage.

The run_cim_operations.py script needs a particular MOF file loaded in the repository of the WBEM server that is used for the test. This can be done using the MOF compiler of pywbem:
```
$ mof_compiler -s <target_url> tests/unittest/pywbem/test.mof
```

To run the unit and function tests in all supported Python environments, the Tox tool can be used. It creates the necessary virtual Python environments and executes make test (i.e. the unit and function tests) in each of them.

For running Tox, it does not matter which Python environment is currently active, as long as the Python tox package is installed in it:

$ tox                              # Run tests on all supported Python versions
$ tox -e py27                      # Run tests on Python 2.7

Testing from the source archives on Pypi or GitHub

The wheel distribution archives on Pypi (e.g. pywbem-1.0.0-py2.py3-none-any.whl) contain only the files needed to run pywbem, but not the files needed to test it.

The source distribution archives on Pypi and GitHub (e.g. pywbem-1.0.0.tar.gz) contain all files that are needed to run and to test pywbem.

This allows testing pywbem without having to check out the entire repository, and is convenient for testing e.g. when packaging pywbem into OS-level packages.

When installing these source distribution archives, the files needed for running pywbem are installed into the active Python environment, but not the test files.

The following commands download the source distribution archive on Pypi for a particular version of pywbem into the current directory and unpack it:

$ pip download --no-deps --no-binary :all: pywbem==1.0.0
$ tar -xf pywbem-1.0.0.tar.gz
$ cd pywbem-1.0.0
$ ls -1
-rw-r--r--   1 maiera  staff    468 Jun 29 22:31 INSTALL.md
-rw-r--r--   1 maiera  staff  26436 May 26 06:45 LICENSE.txt
-rw-r--r--   1 maiera  staff    367 Jul  3 07:54 MANIFEST.in
-rw-r--r--   1 maiera  staff   3451 Jul  3 07:55 PKG-INFO
-rw-r--r--   1 maiera  staff   7665 Jul  2 23:20 README.rst
-rw-r--r--   1 maiera  staff   1624 Jul  2 23:20 README_PYPI.rst
-rwxr-xr-x   1 maiera  staff   2881 Jun 29 22:31 build_moftab.py
-rwxr-xr-x   1 maiera  staff  13850 Jun 29 22:31 mof_compiler
-rw-r--r--   1 maiera  staff    105 May 26 06:45 mof_compiler.bat
drwxr-xr-x  29 maiera  staff    928 Jul  3 07:55 pywbem
drwxr-xr-x   8 maiera  staff    256 Jul  3 07:55 pywbem.egg-info
drwxr-xr-x  18 maiera  staff    576 Jul  3 07:55 pywbem_mock
-rw-r--r--   1 maiera  staff   1067 Jun 29 22:31 requirements.txt
-rw-r--r--   1 maiera  staff     38 Jul  3 07:55 setup.cfg
-rwxr-xr-x   1 maiera  staff   7555 Jul  3 07:24 setup.py
-rw-r--r--   1 maiera  staff   2337 Jul  2 23:20 test-requirements.txt
drwxr-xr-x  15 maiera  staff    480 Jul  3 07:55 tests

Pywbem, its dependent packages, and packages needed for testing pywbem can be installed with the package extra named “test”:

$ pip install .[test]

When testing pywbem installations in Linux distributions that include pywbem as an OS-level package, the corresponding OS-level packages would instead be installed for these dependent Python packages. The test-requirements.txt file shows which dependent Python packages are needed for testing pywbem.

Finally, the tests can be run using the setup.py script:

$ ./setup.py test
$ ./setup.py leaktest
$ ./setup.py end2endtest

These commands are listed in the help of the setup.py script:

$ ./setup.py --help-commands
. . .
Extra commands:
  . . .
  test              pywbem: Run unit and function tests using pytest
  leaktest          pywbem: Run leak tests using pytest
  end2endtest       pywbem: Run end2end tests using pytest
  . . .

The additional options supported by these commands are shown in their help:

$ ./setup.py test --help
. . .
Options for 'test' command:
  --pytest-options  additional options for pytest, as one argument
. . .

Note: The test command of setup.py is not the deprecated built-in command (see https://github.com/pypa/setuptools/issues/1684), but has been implemented in setup.py in such a way that it only runs the tests but does not install anything upfront. The leaktest and end2endtest commands have been implemented in the same way. Therefore, this approach can be used for testing pywbem installations from OS-level packages in Linux distributions that include pywbem.

Testing installed versions of pywbem

By default, the tests use the pywbem and pywbem_mock modules from the respective directories in the Git repo work directory.

Pywbem 0.14.5 introduced a way to test installed versions of the pywbem package. This is useful for example for testing a version of pywbem that has been packaged as an OS-level package. Typically, such a version would be installed into the system Python.

Some words of caution:

Testing an installed version of pywbem with test cases from a pywbem repo of a different version can result in failing test cases for several reasons:
- If a new version of pywbem has added functionality, its test cases are also extended accordingly. Running such newer test cases against an older installed version of pywbem may fail simply because the installed version does not yet have the added functionality.
- Fixes in pywbem or in the test cases may change behavior in a subtle way that causes test cases to fail.
- Unit test cases are particularly vulnerable to version mismatches because they test at the module level, including module interfaces that are internal to pywbem and thus can legally change incompatibly between versions.
If the version of the installed pywbem is before 0.14.5, some test cases that compile MOF will be skipped to avoid permission denied errors when ply attempts to re-generate its parsing table files in the pywbem installation directory in case of ply version mismatches. Starting with pywbem 0.14.5, it has tolerance against ply version mismatches.

In order to not clutter up the system Python with Python packages needed for running the pywbem tests, the following steps use a virtual Python environment that uses the packages of the system Python. That way, the installed version of pywbem becomes available to the virtual Python environment from the system Python, while any additional packages that are needed but not yet available that way, will be installed into the virtual Python environment.

Follow these steps to run pywbem tests against a version of pywbem that is installed into the system Python:

Verify that the following commands are available when the system Python is active:
```
$ virtualenv --version   # Python virtualenv package
$ pip --version
```
Create and activate a virtual Python environment of the intended Python version, that is based on the system Python:
```
$ virtualenv --system-site-packages --no-setuptools --no-pip --no-wheel .virtualenv/test
$ source .virtualenv/test/bin/activate
```
The pywbem project is set up so that Git ignores the .virtualenv directory, so use that directory name for ease of Git handling.
Verify that in that virtual Python environment, pywbem comes from the intended installation:
```
$ pip show pywbem
```
Ensure a fresh start of the make process. This should be done whenever switching between the installed version of pywbem and the local directories:
```
$ make clobber
```
Run the pywbem tests with environment variable TEST_INSTALLED being set:
```
$ TEST_INSTALLED=1 make test
```
This will assume that the pywbem package and any prerequisite Python packages and OS-level packages are already installed.

This will also move the current directory (i.e. the repo working directory) to the end of the module search path, so that the installed version of pywbem is used when importing it into the test scripts.

Setting TEST_INSTALLED=DEBUG causes some debug messages to be printed that allow verifying from where the pywbem and pywbem_mock modules are loaded.

This also works for the pywbem end2end tests:
```
$ TEST_INSTALLED=1 make end2end
```

Note that tox does not support creating its virtual Python environments based on the system Python, so at this point, tox cannot be used for this approach.

Updating the DMTF MOF Test Schema

Pywbem uses DMTF CIM Schemas in its CI testing. The schema used is stored in the form received from the DMTF in the directory tests/schema and is expanded and compiled as part of the unit tests.

Since the DMTF regularly updates the schema, the pywbem project tries to stay up-to-date with the current schema. At the same time, earlier schemas can be used for testing also by changing the definitions for the dmtf schema to be tested.

The schema used for testing can be modified by modifying the test file:

tests/unittest/utils/dmtf_mof_schema_def.py

Developing PyWBEM Ipython Documentation Notebooks

The pywbem developers are using ipython notebooks to demonstrate the use of pywbem. Today we generally have one notebook per operation or group of operations including definition of the operation, references back to the pywbem documentation, and one or more examples (hopefully examples that will actually execute against a wbem server)

These can easily be extended or supplemented using a local ipython or jupyter server by:

1. Install ipython or Jupyter software using pip or pip3. The notebook server may be installed as root or within a python virtual environment. For example:

$ sudo pip install ipython
or
$ sudo pip3 install ipython
or
$ sudo pip install jupyter

The notebook server may be installed as root or within a python virtual environment.

2. Start the local ipython/jupyter notebook server in the notebook directory (pywbem/docs/notebooks) referencing that directory in the command line call:

$ ipython notebook docs/notebooks
or
$ jupyter notebook docs/notebooks

This will start the local ipython/juypter notebook server and on the first page displayed in your web browser all existing pywbem ipython notebooks will be available for editing. New ones can be created using the commands on that ipython server web page.

New and changed notebooks must go through the same contribution process as other components of pywbem to be integrated into the github repository.

Contributing

Third party contributions to this project are welcome!

In order to contribute, create a Git pull request, considering this:

Test is required.
Each commit should only contain one “logical” change.
A “logical” change should be put into one commit, and not split over multiple commits.
Large new features should be split into stages.
The commit message should not only summarize what you have done, but explain why the change is useful.
The commit message must follow the format explained below.

What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.

For further discussion of good and bad practices regarding commits, see:

Core Development Team

Anyone can contribute to pywbem via pull requests as described in the previous section.

The pywbem project has a core development team that holds regular web conferences and that is using Slack for offline communication, on the Slack workspace: https://pywbem.slack.com.

The web conference and the Slack workspace are by invitation, and if you want to participate in the core team, please open an issue to let us know.

Appendix

This section contains information that is referenced from other sections, and that does not really need to be read in sequence.

Special type names

This documentation uses a few special terms to refer to Python types:

string

a unicode string or a byte string

unicode string

a Unicode string type (unicode in Python 2, and str in Python 3)

byte string

a byte string type (str in Python 2, and bytes in Python 3). Unless otherwise indicated, byte strings in pywbem are always UTF-8 encoded.

connection id

a string (string) that uniquely identifies each pywbem.WBEMConnection object created. The connection id is immutable and is accessible from pywbem.WBEMConnection.conn_id. It is included in of each log record created for pywbem log output and may be used to correlate pywbem log records for a single connection.

number

one of the number types int, long (Python 2 only), or float.

integer

one of the integer types int or long (Python 2 only).

callable

a callable object; for example a function, a class (calling it returns a new object of the class), or an object with a __call__() method.

hashable

a hashable object. Hashability requires an object not only to be able to produce a hash value with the hash() function, but in addition that objects that are equal (as per the == operator) produce equal hash values, and that the produced hash value remains unchanged across the lifetime of the object. See term “hashable” in the Python glossary, although the definition there is not very crisp. A more exhaustive discussion of these requirements is in “What happens when you mess with hashing in Python” by Aaron Meurer.

unchanged-hashable

an object that is hashable with the exception that its hash value may change over the lifetime of the object. Therefore, it is hashable only for periods in which its hash value remains unchanged. CIM objects are examples of unchanged-hashable objects in pywbem.

DeprecationWarning

a standard Python warning that indicates a deprecated functionality. See section Deprecation and compatibility policy and the standard Python module warnings for details.

Element

class xml.dom.minidom.Element. Its methods are described in section Element Objects of module xml.dom, with minidom specifics described in section DOM Objects of module xml.dom.minidom.

CIM data type

one of the types listed in CIM data types.

CIM object

one of the types listed in CIM objects.

CIM namespace

an object that is accessible through a WBEM server and is a naming space for CIM classes, CIM instances and CIM qualifier declarations. The namespace is a component of other elements like namespace path used to access objects in the WBEM server.

NocaseList

A case-insensitive list class provided by the nocaselist package.

interop namespace

A CIM namespace is the interop namespace if it has one of the following names: DMTF definition; (‘interop’, ‘root/interop’) pywbem implementation; (‘interop’, ‘root/interop’, ‘root/PG_Interop’), Only one interop namespace is allowed in a WBEM Server. The interop namespace contains CIM classes that the client needs to discover characteristics of the WBEM server (namespaces, coniguration of server components like indications) and the registered profiles implemented by that server.

keybindings input object

a Python object used as input for initializing an ordered list of keybindings in a parent object (i.e. a CIMInstanceName object).

None will result in an an empty list of keybindings.

Otherwise, the type of the input object must be one of:

iterable of CIMProperty
iterable of tuple(key, value)
OrderedDict with key and value
dict with key and value (will not preserve order)

with the following definitions for key and value:

key (string): Keybinding name.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or number or CIMProperty): Keybinding value.

If specified as CIM data type or number, the provided object will be stored unchanged as the keybinding value.

If specified as a CIMProperty object, its name attribute must match the key (case insensitively), and a copy of its value (a CIM data type) will be stored as the keybinding value.

None for the keybinding value will be stored unchanged.

If the WBEM server requires the TYPE attribute on KEYVALUE elements to be set in operation requests, this can be achieved by specifying the keybinding value as CIM data type (either directly, or via a CIMProperty object).

The order of keybindings in the parent object is preserved if the input object is an iterable or a OrderedDict object, but not when it is a dict object.

The resulting set of keybindings in the parent object is independent of the input object (except for unmutable objects), so that subsequent modifications of the input object by the caller do not affect the parent object.

methods input object

a Python object used as input for initializing an ordered list of methods represented as CIMMethod objects in a parent object that is a CIMClass.

None will result in an an empty list of methods.

Otherwise, the type of the input object must be one of:

iterable of CIMMethod
iterable of tuple(key, value)
OrderedDict with key and value
dict with key and value (will not preserve order)

with the following definitions for key and value:

key (string): Method name.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIMMethod): Method declaration.

Must not be None.

The name attribute of the CIMMethod object must match the key (case insensitively).

The provided object is stored in the parent object without making a copy of it.

The order of methods in the parent object is preserved if the input object is an iterable or a OrderedDict object, but not when it is a dict object.

The resulting set of methods in the parent object is independent of the input collection object, but consists of the same CIMMethod objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the provided CIMMethod objects.

parameters input object

a Python object used as input for initializing an ordered list of parameters represented as CIMParameter objects in a parent object that is a CIMMethod.

None will result in an an empty list of parameters.

Otherwise, the type of the input object must be one of:

iterable of CIMParameter
iterable of tuple(key, value)
OrderedDict with key and value
dict with key and value (will not preserve order)

with the following definitions for key and value:

key (string): Parameter name.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIMParameter): Parameter (declaration).

Must not be None.

The name attribute of the CIMParameter object must match the key (case insensitively).

The provided object is stored in the parent object without making a copy of it.

The order of parameters in the parent object is preserved if the input object is an iterable or a OrderedDict object, but not when it is a dict object.

The resulting set of parameters in the parent object is independent of the input collection object, but consists of the same CIMParameter objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the provided CIMParameter objects.

properties input object

a Python object used as input for initializing an ordered list of properties represented as CIMProperty objects, in a parent object.

The CIMProperty objects represent property values when the parent object is a CIMInstance, and property declarations when the parent object is a CIMClass.

None will result in an an empty list of properties.

Otherwise, the type of the input object must be one of:

iterable of CIMProperty
iterable of tuple(key, value)
OrderedDict with key and value
dict with key and value (will not preserve order)

with the following definitions for key and value:

key (string): Property name.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or CIMProperty): Property (value or declaration).

Must not be None.

CIMProperty objects can be used as input for both property values and property declarations. CIM data type objects can only be used for property values.

If specified as a CIM data type, a new CIMProperty object will be created from the provided value, inferring its CIM data type from the provided value.

If specified as a CIMProperty object, its name attribute must match the key (case insensitively), and the provided object is stored in the parent object without making a copy of it.

The order of properties in the parent object is preserved if the input object is an iterable or a OrderedDict object, but not when it is a dict object.

The resulting set of properties in the parent object is independent of the input collection object, but consists of the same CIMProperty objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the provided CIMProperty objects.

provider

An element of a WBEM server that responds to requests for selected classes. A WBEM server normally contains a main provider that may interface with a CIM respository and provides responses to client requests for which no specific provider is defined and providers which providers that allow specialized responses for selected classes and request types (communicate with managed components) or manipulate the objects being managed.

NOTE: In the SNIA terminology, a provider may also be a complete WBEM server implementation.

user-defined provider

A :term:provider that can be defined independently of the WBEM server and attached dynamically to the WBEM server. In pywbem, user-defined providers can be defined as subclasses of specific default provider types and attached to the server by registering them with the connection.

qualifiers input object

a Python object used as input for initializing an ordered list of qualifiers represented as CIMQualifier objects in a parent object (e.g. in a CIMClass object).

None will result in an an empty list of qualifiers.

Otherwise, the type of the input object must be one of:

iterable of CIMQualifier
iterable of tuple(key, value)
OrderedDict with key and value
dict with key and value (will not preserve order)

with the following definitions for key and value:

key (string): Qualifier name.

Must not be None.

The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or CIMQualifier): Qualifier (value).

Must not be None.

If specified as a CIM data type, a new CIMQualifier object will be created from the provided value, inferring its CIM data type from the provided value.

If specified as a CIMQualifier object, its name attribute must match the key (case insensitively), and the provided object is stored in the parent object without making a copy of it.

The order of qualifiers in the parent object is preserved if the input object is an iterable or a OrderedDict object, but not when it is a dict object.

The resulting set of qualifiers in the parent object is independent of the input collection object, but consists of the same CIMQualifier objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the provided CIMQualifier objects.

Profile advertisement methodologies

This section briefly explains the profile advertisement methodologies defined by DMTF. A full description can be found in DSP1033.

These methodologies describe how a client can discover the central instances of a management profile. Discovering the central instances through a management profile is the recommended approach for clients, over simply enumerating a CIM class of choice. The reason is that this approach enables clients to work seamlessly with different server implementations, even when they have implemented a different set of management profiles.

DMTF defines three profile advertisement methodologies in DSP1033:

GetCentralInstances methodology (new in DSP1033 1.1)
Central class methodology
Scoping class methodology

At this point, the GetCentralInstances methodology has not widely been implemented, but pywbem supports it nevertheless.

All three profile advertisement methodologies start from the CIM_RegisteredProfile instance that identifies the management profile, by means of registered organisation, registered name, and registered version.

It is important to understand that the CIM_RegisteredProfile instance not only identifies the management profile, but represents a particular use of the management profile within its scoping profiles. For an autonomous profile, there are no scoping profiles, so in that case, there is only one use of the autonomous profile in a server. However, component profiles do have scoping profiles, and it is well possible that a component profile is used multiple times in a server, in different scoping contexts. If that is the case, and if discovery of central instances using any of the profile advertisement methodologies is supposed to work, then each such use of the profile needs to have its own separate CIM_RegisteredProfile instance, because each such use of the profile will also have its own separate set of central instances.

Unfortunately, neither the DMTF standards nor the SMI-S standards are clear about that requirement, and so there are plenty of implementations that share a single CIM_RegisteredProfile instance identifying a particular component profile, for multiple distinct uses of the profile by its scoping profiles. In such a case, the profile advertisement methodologies will not be able to distinguish the distinct sets of central instances alone, and other means need to be used to distinguish them.

It is also important to understand that the choice which profile advertisement methodology to implement, is done by the WBEM server side. Therefore, a WBEM client such as pywbem needs to support all methodologies and needs to try them one by one until one succeeds. Pywbem tries the three methodologies in the order listed above.

In the GetCentralInstances methodology, the CIM_RegisteredProfile instance has a CIM method named GetCentralInstances that returns the instance paths of the central instances of the use of the profile.

In the central class methodology, the CIM_RegisteredProfile instance is associated directly with the set of central instances of the use of the profile, via a CIM_ElementConformsToProfile association.

In the scoping class methodology, the CIM_RegisteredProfile instance is not associated directly with the set of central instances of the use of the profile, but delegates that to its scoping profile. The client navigates up to the CIM_RegisteredProfile instance representing the (use of the) scoping profile, looks up its central instances, and from each of those, navigates down along the reversed scoping path to the central instances of the profile in question. The scoping path of a component profile describes the traversal across associations and ordinary classes from the central class to the scoping class of the profile. This profile advertisement methodology is obviously the most complex one of the three.

Pywbem encapsulates the complexity and choice of these methodologies into a single invocation of an easy-to use method get_central_instances().

Profile implementations in a WBEM server are not entirely free when making a choice of which methodology to implement:

Autonomous profiles in a WBEM server must implement the central class methodology, and may in addition implement the new GetCentralInstances methodology.

Note that the scoping class methodology falls together with the central class methodology for autonomous profiles, because their scoping class is also their central class.
Component profiles in a WBEM server may implement the central class methodology and the new GetCentralInstances methodology, and must support the scoping class methodology.

Note that implementing the scoping class methodology in a WBEM server requires implementing the classes and associations of the scoping path, which are usually mandatory anyway. So while the scoping class methodology is more complex to use for clients than the central class methodology, it is easier to implement for servers.

Use of the scoping class methodology by a client requires knowing the central class, scoping class and scoping path defined by the component profile.

DSP1001 requires that conformant autonomous profiles specify a central class, and that conformant component profiles specify a central class, scoping class and a scoping path.

Older DMTF component profiles and older SNIA subprofiles do not always specify scoping class and scoping path. In such cases, the scoping class and scoping path can often be determined from the class diagram in the specification for the profile. Many times, CIM_System or CIM_ComputerSystem is the scoping class.

Troubleshooting

Here are some trouble shooting hints for the installation of pywbem.

Installation fails with “invalid command ‘bdist_wheel’”

The installation of some Python packages requires the Python “wheel” package. If that package is not installed in the current Python environment, the installation will fail with the following (or similar) symptom:

python setup.py bdist_wheel
usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
or: setup.py --help [cmd1 cmd2 ...]
or: setup.py --help-commands
or: setup.py cmd --help
error: invalid command 'bdist_wheel'

To fix this, install the Python “wheel” package:

pip install wheel

Installation of lxml misses include files on Python 3.4 on native Windows

On Python 3.4 on native Windows, the installation of the lxml Python package may fail during installation of the development prerequisites (i.e. during make develop), reporting missing include files such as libxml/xmlversion.h.

It has not been investigated what causes this on Python 3.4 (it works on other Python versions). If this issue shows up, try installing the Binary lxml package for Windows manually, with the lxml version >=4.2.4 and <4.4.0.

ConnectionError raised with [SSL: UNSUPPORTED_PROTOCOL]

On newer versions of the operating system running the pywbem client, communication with the WBEM server may fail with:

pywbem.exceptions.ConnectionError: SSL error <class 'ssl.SSLError'>:
  [SSL: UNSUPPORTED_PROTOCOL] unsupported protocol (_ssl.c:1056)

For example, this happened after an upgrade of the client OS to Debian buster using Python 3.7, with OpenSSL 1.1.1d.

This is an error that is created by the OpenSSL library and handed back up to the SSL module of Python which hands it up to pywbem. The error indicates that OpenSSL and the WBEM server do not agree about which SSL/TLS protocol level to use.

Pywbem specifies SSL parameters such that the highest SSL/TLS protocol version is used that both the client and server support. Thus, pywbem does not put any additional restrictions on top of OpenSSL.

Debian buster includes OpenSSL 1.1.1d and increased its security settings to require at least TLS 1.2 (see https://stackoverflow.com/a/53065682/1424462).

This error means most likely that the WBEM server side does not yet support TLS 1.2 or higher.

This can be fixed for example by adding TLS 1.2 support to the server side (preferred) or by lowering the minimum TLS level OpenSSL requires on the client side (which lowers security). The latter can be done by changing the MinProtocol parameter in the OpenSSL config file on the client OS (typically /etc/ssl/openssl.cnf on Linux and OS-X, and C:\OpenSSL-Win64\openssl.cnf on Windows). At the end of the file there is:

[system_default_sect]
MinProtocol = TLSv1.2
CipherString = DEFAULT@SECLEVEL=2

ConnectionError raised with [SSL] EC lib

Using pywbem on Python 3.5 with OpenSSL 1.0.1e-fips against an IBM DS8000 raised the following exception:

pywbem.exceptions.ConnectionError: SSL error <class 'ssl.SSLError'>:
  [SSL] EC lib (_ssl.c:728)

This is an error that is created by the OpenSSL library and handed back up to the SSL module of Python which hands it up to pywbem. The error indicates that OpenSSL on the client side cannot deal with the cipher used by the server side. This was fixed by upgrading OpenSSL on the client OS to version 1.1.1.

Base classes

Some bases classes are included in this documentation in order to provide the descriptions for inherited methods and properties that are referenced from the summary tables in other class descriptions.

class pywbem._exceptions._RequestExceptionMixin(*args, **kwargs)[source]

An internal mixin class for pywbem specific exceptions that provides the ability to store the CIM-XML request string in the exception.

New in pywbem 1.0.

Derived classes using this mixin class need to specify it before the base error class.

Parameters

*args – Any other positional arguments are passed on to the next superclass.
**kwargs – Any other keyword arguments are passed on to the next superclass.
request_data (string) – CIM-XML request string. Omitted or None means the exception does not store a CIM-XML request. Must be specified as a keyword argument; if specified it will be removed from the keyword arguments that are passed on.

Attributes:

request_data

CIM-XML request string (settable).

property request_data

CIM-XML request string (settable). None if the exception does not store a CIM-XML request.

Type: string

class pywbem._exceptions._ResponseExceptionMixin(*args, **kwargs)[source]

Mixin class into pywbem specific exceptions that provides the ability to store the CIM-XML response string in the exception.

New in pywbem 1.0.

Derived classes using this mixin class need to specify it before the base error class.

Parameters

*args – Any other positional arguments are passed on to the next superclass.
**kwargs – Any other keyword arguments are passed on to the next superclass.
response_data (string) – CIM-XML response string. Omitted or None means the exception does not store a CIM-XML response. Must be specified as a keyword argument; if specified it will be removed from the keyword arguments that are passed on.

Attributes:

response_data

CIM-XML response string (settable).

property response_data

CIM-XML response string (settable). None if the exception does not store a CIM-XML response.

Type: string

class pywbem._cim_types._CIMComparisonMixin[source]

Mixin class providing default implementations for equality test operators and hash function.

The implementations of ordering tests are also provided and raise an exception because ordering of CIM objects is not supported.

In Python 2, the rich comparison operators (e.g. __eq__()) have precedence over the traditional comparator method (__cmp__()). In Python 3, the comparator method (__cmp__()) no longer exists. Therefore, implementing the rich comparison operators works in both.

Methods:

`__eq__`(other)	Equality test for two CIM objects.
`__hash__`()	Interface definition for hash function to be provided by subclasses.
`__ne__`(other)	Non-equality test for two CIM objects.

__eq__(other)[source]

Equality test for two CIM objects.

The comparison must be implemented in the derived class.

__hash__()[source]

Interface definition for hash function to be provided by subclasses.

Background: In order to behave as expected in sets and other hash-based collections, the hash values of objects must be equal when the objects themselves are considered equal. The default hash function for classes is based on id() and therefore does not satisfy that requirement.

Therefore, the CIM objects need to implement a hash function that satisfies that requirement.

__ne__(other)[source]

Non-equality test for two CIM objects.

The comparison is delegated to the __eq__() method, because we require it to be implemented. See https://stackoverflow.com/a/30676267/1424462 for discussion about delegating to == vs. __eq__().

class pywbem_mock.BaseRepository[source]

An abstract base class defining the required APIs to provide access to a a CIM repository.

New in pywbem 1.0 as experimental and finalized in 1.2.

The API provides functions to:

Manage CIM namespaces in the data repository including creation, deletion and getting a list of the existing namespaces.
Access the object store for each CIM object type in the repository for the objects of the following CIM types: (CIMClass, CIMInstance, and CIMQualifierDeclaration) so that methods of the BaseObjectStore are used to access and manipulate CIM objects of a single CIM type by namespace in the repository.

Methods:

`add_namespace`(namespace)	Add a CIM namespace to the repository.
`get_class_store`(namespace)	Return the CIM class object store for the namespace provided.
`get_instance_store`(namespace)	Return the CIM instance object store for the namespace provided.
`get_qualifier_store`(namespace)	Return the CIM qualifier declaration object store for the namespace provided.
`remove_namespace`(namespace)	Remove a CIM namespace from the repository.
`validate_namespace`(namespace)	Validate if the namespace exists in the repository.

Attributes:

namespaces

NocaseList of string: The names of the namespaces that exist in this CIM repository.

abstract add_namespace(namespace)[source]

Add a CIM namespace to the repository.

The namespace must not yet exist in the CIM repository.

Parameters: namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.
Raises: ValueError – If the namespace argument is None or the namespace already exists.

abstract get_class_store(namespace)[source]

Return the CIM class object store for the namespace provided.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Returns

CIM class object store for the namespace provided.

Return type

Raises

ValueError – Namespace argument is None.
KeyError – Namespace does not exist in the repository

abstract get_instance_store(namespace)[source]

Return the CIM instance object store for the namespace provided.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Returns

CIM instance object store for the namespace provided.

Return type

Raises

ValueError – Namespace argument is None.
KeyError – Namespace argument does exist in the repository.

abstract get_qualifier_store(namespace)[source]

Return the CIM qualifier declaration object store for the namespace provided.

Parameters

namespace (string) – The name of the CIM namespace in the CIM repository. The name is treated case insensitively and it must not be None. Any leading and trailing slash characters in the namespace string are ignored when accessing the repository.

Returns

CIM qualifier declaration object store for the namespace provided.

Return type