4. WBEM client library API

The WBEM client library API supports issuing WBEM operations to a WBEM server, using the CIM operations over HTTP (CIM-XML) protocol defined in the DMTF standards DSP0200 and DSP0201.

This chapter has the following sections:

  • WBEM operations - Class WBEMConnection is the main class of the WBEM client library API and is used to issue WBEM operations to a WBEM server.
    • WBEM Operation recording - Class WBEMConnection includes the capability to optionally record the WBEMConnection method calls that communicate with a WBEM server including creating yaml files for test generation and logging using the Python logging facility.
  • CIM objects - Python classes for representing CIM objects (instances, classes, properties, etc.) that are used by the WBEM operations as input or output.
  • CIM data types - Python classes for representing values of CIM data types.
  • CIM status codes - CIM status codes returned by failing WBEM operations.
  • Logging - Logging of WBEM operations.
  • Exceptions - Exceptions specific to pywbem that may be raised.
  • Statistics - Statistics classes to gather information on wbem operation performance.
  • WBEM Operation recorder - Python classes that implement the operation recorder functions that are used by WBEMConnection.
  • Security considerations - Information about authentication types and certificates.

A number of these topics apply also to the other APIs of the pywbem package.

4.1. WBEM operations

Objects of the WBEMConnection class represent a connection to a WBEM server. All WBEM operations defined in DSP0200 can be issued across this connection. Each method of this class corresponds directly to a WBEM operation.

WBEMConnection method Purpose
EnumerateInstanceNames() Enumerate the instance paths of instances of a class (including instances of its subclasses).
EnumerateInstances() Enumerate the instances of a class (including instances of its subclasses)
GetInstance() Retrieve an instance
ModifyInstance() Modify the property values of an instance
CreateInstance() Create an instance
DeleteInstance() Delete an instance
AssociatorNames() Retrieve the instance paths of the instances (or classes) associated to a source instance (or source class)
Associators() Retrieve the instances (or classes) associated to a source instance (or source class)
ReferenceNames() Retrieve the instance paths of the association instances (or association classes) that reference a source instance (or source class)
References() Retrieve the association instances (or association classes) that reference a source instance (or source class)
InvokeMethod() Invoke a method on a target instance or on a target class
ExecQuery() Execute a query in a namespace
IterEnumerateInstances() Experimental: Iterator API that uses either OpenEnumerateInstances and PullInstancesWithPath or EnumerateInstances depending on the attributes and existence of pull operations in the server.
IterEnumerateInstancePaths() Experimental: Iterator API that uses either OpenEnumerateInstances and PullInstancesWithPath or EnumerateInstances depending on the attributes and existence of pull operations in the server.
IterReferenceInstances() Experimental: Iterator API that uses either OpenReferenceInstances and PullInstancesWithPath or References depending on the attributes and existence of pull operations in the server.
IterReferenceInstancePaths() Experimental: Iterator API that uses either OpenReferenceInstances and PullInstancesWithPath or References depending on the attributes and existence of pull operations in the server.
IterAssociatorInstances() Experimental: Iterator API that uses either OpenAssociatorInstances and PullInstancesWithPath or Associators depending on the attributes and existence of pull operations in the server.
IterAssociatorInstancePaths() Experimental: Iterator API that uses either OpenAssociatorInstances and PullInstancesWithPath or Associators depending on the attributes and existence of pull operations in the server.
IterQueryInstances() Experimental: Iterator API that uses either OpenQueryInstances and PullInstances or ExecQuery depending on the attributes and existence of pull operations in the server.
OpenEnumerateInstances() Open enumeration session to retrieve instances of of a class (including instances of its subclass)
OpenAssociatorInstances() Open enumeration session to retrieve the instances associated to a source instance
OpenReferenceInstances() Open enumeration session to retrieve the instances that reference a source instance
PullInstancesWithPath() Continue enumeration session opened with OpenEnumerateInstances, OpenAssociatorInstances, or OpenReferenceinstances
OpenEnumerateInstancePaths() Open enumeration session to retrieve instances of a class (including instances of its subclass)
OpenAssociatorInstancePaths() Open enumeration session to retrieve the instances associated to a source instance
OpenReferenceInstancePaths() Open enumeration session to retrieve the instances that reference a source instance
PullInstancePaths() Continue enumeration session opened with OpenEnumerateInstancePaths, OpenAssociatorInstancePaths, or OpenReferenceInstancePaths
OpenQueryInstances() Open query request to retrieve instances defined by the query parameter in a namespace
PullInstances() Continue enumeration of enumeration session opened with OpenExecQuery
CloseEnumeration() Close an enumeration session in process.
EnumerateClassNames() Enumerate the names of subclasses of a class, or of the top-level classes in a namespace
EnumerateClasses() Enumerate the subclasses of a class, or the top-level classes in a namespace
GetClass() Retrieve a class
ModifyClass() Modify a class
CreateClass() Create a class
DeleteClass() Delete a class
EnumerateQualifiers() Enumerate qualifier declarations
GetQualifier() Retrieve a qualifier declaration
SetQualifier() Create or modify a qualifier declaration
DeleteQualifier() Delete a qualifier declaration

NOTE: The method EnumerationCount is to be deprecated from the DMTF specs and has not been implemented by any servers so was not implemented in pywbem

4.1.1. WBEMConnection

class pywbem.WBEMConnection(url, creds=None, default_namespace='root/cimv2', x509=None, verify_callback=None, ca_certs=None, no_verification=False, timeout=None, use_pull_operations=False, enable_stats=False)[source]

A client’s connection to a WBEM server. This is the main class of the WBEM client library API.

The connection object knows a default CIM namespace, which is used when no namespace is specified on subsequent WBEM operations (that support specifying namespaces). Thus, the connection object can be used as a connection to multiple CIM namespaces on a WBEM server (when the namespace is specified on subsequent operations), or as a connection to only the default namespace (this allows omitting the namespace on subsequent operations).

As usual in HTTP, there is no persistent TCP connection; the connectedness provided by this class is only conceptual. That is, the creation of the connection object does not cause any interaction with the WBEM server, and each subsequent WBEM operation performs an independent, state-less HTTP/HTTPS request.

After creating a WBEMConnection object, various methods may be called on the object, which cause WBEM operations to be issued to the WBEM server. See WBEM operations for a list of these methods.

CIM elements such as instances or classes are represented as Python objects (see CIM objects). The caller does not need to know about the CIM-XML encoding of CIM elements and protocol payload that is used underneath (It should be possible to use a different WBEM protocol below this layer without disturbing any callers).

The connection remembers the XML of the last request and last reply if debugging is turned on via the debug attribute of the connection object. This may be useful in debugging: If a problem occurs, you can examine the last_request and last_reply attributes of the connection object. These are the prettified XML of request and response, respectively. The real request and response that are sent and received are available in the last_raw_request and last_raw_reply attributes of the connection object.

WBEMConnection objects can record the results of WBEMConnection methods that interact with a WBEM server using either the LogOperationRecorder (uses python logging facitlity to create logs for these methods and http interactions) or the :class:`~pywbem.TestClientRecorder`( creates a yaml file of methods and http for tests)..

Before pywbem version 0.11.0, there was only a single operation recorder and activating/deactivating the recorder was a simple matter of setting the value of an instance of the TestClientRecorder into the WBEMConnection.operation_recorder attribute. Setting the value of TestClientRecorder into this attribute activated and enabled the recorder. Setting it to None deactivated the recorder.

Starting with pywbem version 0.11.0, pywbem added a second recorder and the requirement that both recorders operate simultaneously. Thus, if both are enabled and active, operation data can be both recorded to a yaml file and to the log simultaneously.

The method to activate has therefore change. To activate a recorder you must use the WBEM connection method:

The methods of this class may raise the following exceptions:

  • Exceptions indicating processing errors:

    • ConnectionError - A connection with the WBEM server could not be established or broke down.
    • AuthError - Authentication failed with the WBEM server.
    • HTTPError - HTTP error (bad status code) received from WBEM server.
    • ParseError - The response from the WBEM server cannot be parsed (for example, invalid characters or UTF-8 sequences, ill-formed XML, or invalid CIM-XML).
    • CIMError - The WBEM server returned an error response with a CIM status code.
    • TimeoutError - The WBEM server did not respond in time and the client timed out.

  • Exceptions indicating programming errors:

    Exceptions indicating programming errors should not happen. If you think the reason such an exception is raised lies in pywbem, report a bug.

Variables:
  • .. – All parameters of the WBEMConnection constructor are set as public attribute with the same name.
  • .. – There are some additional properties documented for this class, further down.
  • debug (bool) –

    A boolean indicating whether saving of the last request and last reply to the WBEMConnection object is enabled.

    The initial value of this attribute is False. Debug saving can be enabled for future operations by setting this attribute to True.

  • last_request (unicode string) – CIM-XML data of the last request sent to the WBEM server on this connection, formatted as prettified XML. Prior to sending the very first request on this connection object, it is None.
  • last_raw_request (unicode string) – CIM-XML data of the last request sent to the WBEM server on this connection, formatted as it was sent. Prior to sending the very first request on this connection object, it is None.
  • last_reply (unicode string) – CIM-XML data of the last response received from the WBEM server on this connection, formatted as prettified XML. Prior to receiving the very first response on this connection object, it is None.
  • last_raw_reply (unicode string) – CIM-XML data of the last response received from the WBEM server on this connection, formatted as it was received. Prior to receiving the very first response on this connection object, it is None.
  • last_request_len (int) – The size of the HTTP body in the CIM-XML request of the last operation, in Bytes. Prior to sending the very first request on this connection object, or if the last operation raised an exception, it is 0.
  • last_reply_len (int) – The size of the HTTP body in the CIM-XML response of the last operation, in Bytes. Prior to receiving the very first response on this connection object, or if the last operation raised an exception, it is 0.
  • operation_recorder (BaseOperationRecorder) – This attribute from version 0.10.0 has become a propererty in 0.11.0. and as a property is marked deprecated
  • use_pull_operations (bool) –

    Indicates whether the client will attempt the use of pull operations in any Iter…() methods. However, each operation has its own internal equivalent flag based on this flag to allow for WBEM servers that implement only some of the pull operations.

    This variable is initially set from the same-named input argument. If it is initially None, it is modified when Iter…() methods are invoked, dependent on the support for pull operations in the WBEM server.

    After the first call , the variable will be either True or False and indicating whether pull operations will be used in this and subsequent Iter…() methods.
Parameters:
  • url (string) –

    URL of the WBEM server, in the format:

    [{scheme}://]{host}[:{port}]

    The following URL schemes are supported:

    • https: Causes HTTPS to be used.
    • http: Causes HTTP to be used.

    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.

    If no port is specified in the URL, the default ports are:

    • If HTTPS is used, port 5989.
    • If HTTP is used, port 5988.

    Examples for some URL formats:

    • "https://10.11.12.13:6988": Use HTTPS to port 6988 on host 10.11.12.13
    • "https://mysystem.acme.org": Use HTTPS to port 5989 on host mysystem.acme.org
    • "10.11.12.13": Use HTTP to port 5988 on host 10.11.12.13
    • "http://[2001:db8::1234]:15988": Use HTTP to port 15988 on host 2001:db8::1234
    • "http://[::ffff.10.11.12.13]": Use HTTP to port 5988 on host ::ffff.10.11.12.13 (an IPv4-mapped IPv6 address)
    • "http://[2001:db8::1234%25eth0]" or "http://[2001:db8::1234-eth0]": Use HTTP to port 5988 to host 2001:db8::1234 (a link-local IPv6 address) using zone identifier eth0
  • creds (tuple() of userid, password) –

    Credentials for HTTP authenticatiion with the WBEM server, as a tuple(userid, password), with:

    • userid (string): Userid for authenticating with the WBEM server.
    • password (string): Password for that userid.

    If None, the client will not generate Authorization headers in the HTTP request. Otherwise, the client will generate an Authorization header using HTTP Basic Authentication.

    See Authentication types for an overview.

  • default_namespace (string) –

    Name of the CIM namespace to be used by default (if no namespace is specified for an operation).

    Default: DEFAULT_NAMESPACE.

  • x509 (dict) –

    X.509 client certificate and key file to be presented to the WBEM server during the TLS/SSL handshake.

    This parameter is ignored when HTTP is used.

    If None, no client certificate is presented to the server, resulting in 1-way authentication to be used.

    Otherwise, the client certificate is presented to the server, resulting in 2-way authentication to be used. This parameter must be a dictionary containing the following two items:

    • "cert_file" (string): The file path of a file containing an X.509 client certificate.
    • "key_file" (string): The file path of a file containing the private key belonging to the public key that is part of the X.509 certificate file.

    See Authentication types for an overview.

  • verify_callback (callable) –

    Registers a callback function that will be called to verify the X.509 server certificate returned by the WBEM server during the TLS/SSL handshake, in addition to the validation already performed by the TLS/SSL support.

    This parameter is ignored when HTTP is used.

    Note that the validation performed by the TLS/SSL support already includes the usual validation, so that normally a callback function does not need to be used. See Verification of the X.509 server certificate for details.

    Warning: This parameter is not used when the python environment is Python 3 because the ssl module does not support it.

    If None, no such callback function will be registered.

    The specified function will be called for the returned certificate, and for each of the certificates in its chain of trust.

    See M2Crypto.SSL.Context.set_verify for details, as well as http://blog.san-ss.com.ar/2012/05/validating-ssl-certificate-in-python.html):

    The callback function must take five parameters:

    • the M2Crypto.SSL.Connection object that triggered the verification.
    • an OpenSSL.crypto.X509 object representing the certificate to be validated (the returned certificate or one of the certificates in its chain of trust).
    • an integer containing the error number (0 in case no error) of any validation error detected by M2Crypto. You can find their meaning in the OpenSSL documentation.
    • an integer indicating the depth (=position) of the certificate to be validated (the one in the second parameter) in the chain of trust of the returned certificate. A value of 0 indicates that the returned certificate is currently validated; any other value indicates the distance of the currently validated certificate to the returned certificate in its chain of trust.
    • an integer that indicates whether the validation of the certificate specified in the second parameter passed or did not pass the validation by M2Crypto. A value of 1 indicates a successful validation and 0 an unsuccessful one.

    The callback function must return True if the verification passes and False otherwise.

  • ca_certs (string) –

    Location of CA certificates (trusted certificates) for verifying the X.509 server certificate returned by the WBEM server.

    This parameter is ignored when HTTP is used.

    The parameter value is either the directory path of a directory prepared using the c_rehash tool included with OpenSSL, or the file path of a file in PEM format.

    If None, default directory paths will be used to look up CA certificates (see DEFAULT_CA_CERT_PATHS).

  • no_verification (bool) –

    Disables verification of the X.509 server certificate returned by the WBEM server during TLS/SSL handshake, disables verification of the hostname, and disables the invocation of a verification function specified in verify_callback.

    If True, verification is disabled; otherwise, verification is enabled.

    This parameter is ignored when HTTP is used.

    Disabling the verification of the server certificate is insecure and should be avoided!

  • timeout (number) –

    Timeout in seconds, for requests sent to the server. If the server did not respond within the timeout duration, the socket for the connection will be closed, causing a TimeoutError to be raised.

    A value of None means that the connection uses the standard timeout behavior of Python sockets, which can be between several minutes and much longer. Because this is somewhat unpredictable, it is recommended to specify a value for the timeout.

    A value of 0 means the timeout is very short, and does not really make any sense.

    Note that not all situations can be handled within this timeout, so for some issues, operations may take longer before raising an exception.

  • use_pull_operations (bool) –

    Controls the use of pull operations in any Iter…() methods, by intializing a corresponding instance variable that is used during any Iter…() methods. The default value (None) will work on any WBEM server whether or not it supports pull operations.

    None means that the Iter…() methods will attempt a pull operation first, and if the WBEM server does not support it, will use a traditional operation. The corresponding instance variable will be adjusted to indicate what the WBEM server supports.

    True means that the Iter…() methods will only use pull operations. If the WBEM server does not support pull operations, a CIMError with status code CIM_ERR_NOT_SUPPORTED will be raised.

    False means that the Iter…() methods will only use traditional operations.

  • enable_stats (bool) –

    Initial enablement status for maintaining statistics about the WBEM operations executed via this connection. See the Statistics section for details.

    Statistics may also be enabled or disabled with the WBEMConnection property stats_enabled. This may be used to view the current status or change the status (ex. conn.stats_enabled(False))

    Experimental: This argument is experimental for this release.
operation_recorder

This is a writeable property; setting this property will cause the defined recorder to be activated.

Effective pywbem 0.10.0 operation_recorder became a property rather than an attribute. The getter operation returns the last value added through the operation_recorder setter.

The setting operation executes WBEMConnection.add_operation_recorder() with the value provided. Since there can be multiple simultaneous recorders, setting operation_recorder to None is no longer valid.

Parameters:() (operation_recorder_object) – Object of a subclass of the BaseOperationRecorder class.
Exceptions:
ValueError if operation_recorder_object is None.

Experimental: This property is experimental for this release.

Deprecated: This property has been marked deprecated. The method WBEMConnection.add_operation_recorder() should be used to activate an operation recorder.

host

unicode string – The {host}[:{port}]``component of the WBEM server's URL, as specified in the ``url attribute.

operation_recorder_enabled

Operation recorder enablement status for connection.

This is a writeable property; setting this property will change the operation recorder enablement status accordingly for all active operation recorders.

This property returns`False` if no operation recorder has been added.

If any recorder in the recorders list has been enabled, it returns True. Otherwise it returns False.

Parameters:value (bool) – Enablement state to which all active recorders are set.

Experimental: This property is experimental for this release.

stats_enabled

bool – Statistics enablement status for this connection.

This is a writeable property; setting this property will change the statistics enablement status accordingly.

Experimental: This property is experimental for this release.

statistics

Statistics – Statistics for this connection.

Statistics are disabled by default and can be enabled via the enable_stats argument when creating a connection object, or later via modifying the stats_enabled property on this connection object. See the Statistics section for more details.

Experimental: This property is experimental for this release.

last_operation_time

float – Elapsed time of the last operation that was executed via this connection in seconds or None.

This time is available only subsequent to the execution of an operation on this connection, and if the statistics are enabled on this connection. Otherwise, the value is None.

Experimental: This property is experimental for this release.

last_server_response_time

float – Server measured response time of the last request. This is optionally returned from the server in HTTP header

This time is available only subsequent to the execution of an operation on this connection if the WBEMServerResponseTime is received from the WBEM server. Otherwise, the value is None.

Experimental: This property is experimental for this release.

__str__()[source]

Return a short representation of the WBEMConnection object for human consumption.

__repr__()[source]

Return a representation of the WBEMConnection object with all attributes (except for the password in the credentials) that is suitable for debugging.

add_operation_recorder(operation_recorder_object)[source]

Adds an operation recorder instance to the list of operation recorders for this WBEMConnection. This allows multiple recorders to be uses simultaneously. It ignores multiple additions of the same recorder.

Parameters:operation_recorder_object( – class:~pywbem.BaseOperationRecorder) This parameter must be an implemented subclass of :class:`~pywbem.BaseOperationRecorder. Adds the object of the defined recorder class to the list of active operation recorders
Exception:
ValueError: If the same recorder class is added multiple times.
operation_recorder_reset(pull_op=False)[source]

Call the recorder reset function for all active recorders

operation_recorder_stage_pywbem_args(method, **kwargs)[source]

Forward the operation method name and arguments to all active operation recorders.

operation_recorder_stage_result(ret, exc)[source]

Forward the operation result parameters to all active operation recorders.

imethodcall(methodname, namespace, response_params_rqd=None, **params)[source]

This is a low-level method that is used by the operation-specific methods of this class (e.g. EnumerateInstanceNames()). This method is not part of the external WBEM client library API; it is being included in the documentation only for tooling reasons.

Deprecated: Calling this function directly has been deprecated and will issue a DeprecationWarning. Users should call the operation-specific methods instead of this method.

methodcall(methodname, localobject, Params=None, **params)[source]

This is a low-level method that is used by the InvokeMethod() method of this class. This method is not part of the external WBEM client library API; it is being included in the documentation only for tooling reasons.

Deprecated: Calling this function directly has been deprecated and will issue a DeprecationWarning. Users should call InvokeMethod() instead of this method.

EnumerateInstanceNames(ClassName, namespace=None, **extra)[source]

Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.

This method performs the EnumerateInstanceNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be enumerated (case independent). If specified as a CIMClassName object, its host attribute will be ignored.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A list of CIMInstanceName objects that are the enumerated instance paths, with its attributes set as follows:

  • classname: Name of the creation class of the instance.
  • keybindings: Keybindings of the instance.
  • namespace: Name of the CIM namespace containing the instance.
  • host: None, indicating the WBEM server is unspecified.
Raises:

Exceptions described in WBEMConnection.
EnumerateInstances(ClassName, namespace=None, LocalOnly=None, DeepInheritance=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]

Enumerate the instances of a class (including instances of its subclasses) in a namespace.

This method performs the EnumerateInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be enumerated (case independent). If specified as a CIMClassName object, its host attribute will be ignored.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • LocalOnly (bool) –

    Controls the exclusion of inherited properties from the returned instances, as follows:

    • If False, inherited properties are not excluded.
    • If True, inherited properties are basically excluded, but the behavior may be WBEM server specific.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    This parameter has been deprecated in DSP0200 and should be set to False by the caller.

  • DeepInheritance (bool) –

    Indicates that properties added by subclasses of the specified class are to be included in the returned instances, as follows:

    • If False, properties added by subclasses are not included.
    • If True, properties added by subclasses are included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    Note, the semantics of the DeepInheritance parameter in EnumerateClasses() and EnumerateClassNames() is different.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instance, as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property in the returned instances, as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A list of CIMInstance objects that are representations of the enumerated instances.

The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

  • classname: Name of the creation class of the instance.
  • keybindings: Keybindings of the instance.
  • namespace: Name of the CIM namespace containing the instance.
  • host: None, indicating the WBEM server is unspecified.
Raises:

Exceptions described in WBEMConnection.
IterEnumerateInstances(ClassName, namespace=None, LocalOnly=None, DeepInheritance=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple EnumerateInstances/OpenEnumerateInstance methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenEnumerateInstances() and PullInstancesWithPath() operations (pull operations) or the EnumerateInstances() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open… function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open… on other pull operation types the first time each type is used.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for EnumerateInstances so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Otherwise, this method raises an exception.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be enumerated (case independent). If specified as a CIMClassName object, its namespace attribute will be used as a default namespace as described for the namespace parameter, and its host attribute will be ignored.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • LocalOnly (bool) –

    Controls the exclusion of inherited properties from the returned instances, as follows:

    • If False, inherited properties are not excluded.
    • If True, inherited properties are basically excluded, but the behavior may be WBEM server specific.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    This parameter has been deprecated in DSP0200 and should be set to False by the caller.

  • DeepInheritance (bool) –

    Indicates that properties added by subclasses of the specified class are to be included in the returned instances, as follows:

    • If False, properties added by subclasses are not included.
    • If True, properties added by subclasses are included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    Note, the semantics of the DeepInheritance parameter in EnumerateClasses() and EnumerateClassNames() is different.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instance, as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property in the returned instances, as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.

    Many WBEM servers do not support this request attribute so that its use is NOT recommended except in special cases.

    If this attribute is True and the method uses the EnumerateInstances option (use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError

  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for each of the open and pull requests issues as part of the execution of this generator.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
    • The default is defined as a system config variable.
    • None is not allowed.

    The choice of MaxObjectCount is client/server dependent but choices between 100 and 1000 typically do not have a significant impact on either memory or overall efficiency.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
Returns:

A Python generator object. Instances can be retrieved by iterating through the object. Instances that are retrieved include the host and namespace component of the instance path.

Example:

insts_iterator = conn.IterEnumerateInstances('CIM_Blah')
for inst in insts_iterator:
    # close if a particular property value found
    if inst.get('thisPropertyName') == 0
        insts_iterator.close()
        break
    else:
        print('instance %s' % inst.tomof())
IterEnumerateInstancePaths(ClassName, namespace=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve instance paths from a WBEM Server. This method frees the user of choices between the multiple EnumerateInstances/OpenEnumerateInstance methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenEnumerateInstancePaths() and PullInstancePaths() operations (pull operations) or the EnumerateInstanceNames() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations are supported for either all or none of the defined Open…. Since the first request determines whether operations continue with the pull operations, if one of the Open… functions is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will decide that None of the operations are supported. Resetting the use_pull_operations to None may be used to override the decision made by the Iter… method for other operations.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for EnumerateInstances so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Otherwise, this method raises an exception.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be enumerated (case independent). If specified as a CIMClassName object, its namespace attribute will be used as a default namespace as described for the namespace parameter, and its host attribute will be ignored.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.

    Many WBEM servers do not support this request attribute so that its use is NOT recommended except in special cases.

    If this attribute is True and the method uses the EnumerateInstances option (use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError

  • MaxObjectCount (Uint32) –

    Maximum number of instance paths the WBEM server may return for each of the open and pull requests issues as part of the execution of this iterator.

    • If positive, the WBEM server is to return no more than the specified number of instance paths.
    • Zero is not allowed; it would mean that zero paths are to be returned for every request issued.
    • The default is defined as a system config variable.
    • None is not allowed.

    The choice of MaxObjectCount is client/server dependent but choices between 100 and 1000 typically do not have a significant impact on either memory or overall efficiency.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
Returns:

A Python:term:generator object. Instance paths can be retrieved by iterating through the object. In all cases the instance paths are complete including host and namespace information.

Example:

paths_iterator = conn.IterEnumerateInstancePaths('CIM_Blah')
for path in paths_iterator:
    print('path %s' % path)
IterReferenceInstancePaths(InstanceName, ResultClass=None, Role=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve references from a WBEM Server. This method frees the user of choices between the multiple ReferenceNames/ReferenceInstancePaths methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenReferenceInstancePaths operation (see :term:`DSP0200()) and EnumerateInstances() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open… function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open… on other pull operation types the first time each type is used.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Otherwise, this method raises an exception.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • ResultClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation because the act of the server filtering requires that it generate instances and then discard them.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
    • The default is defined as a system config variable.
    • None is not allowed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises:

Exceptions described in WBEMConnection.

Example:

insts_iterator = conn.IterReferencePaths('CIM_Blah')
for inst in insts_iterator:
    # close if a particular property value found
    if inst.get('thisPropertyName') == 0
        insts_iterator.close()
        break
    else:
        print('instance %s' % inst.tomof())
IterReferenceInstances(InstanceName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple EnumerateInstances/OpenEnumerateInstance methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenReferenceInstances() and PullInstancesWithPath() operations (pull operations) or the References() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open… function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open… on other pull operation types the first time each type is used.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • ResultClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instances (or classes), as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string) –

    An iterable specifying the names of the properties to be included in the returned instances (or classes) (case independent). An empty iterable indicates to include no properties.

    If None, all properties are included.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
    • The default is defined as a system config variable.
    • None is not allowed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises:

Exceptions described in WBEMConnection.

Example:

insts_iterator = conn.IterReferenceInstances('CIM_Blah.key=1', ...)
for inst in insts_iterator:
    # close if a particular property value found
    if inst.get('thisPropertyName') == 0
        insts_iterator.close()
        break
    else:
        print('instance %s' % inst.tomof())
IterAssociatorInstancePaths(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve associator paths from a WBEM Server. This method frees the user of choices between the multiple AssociatorNames/OpenAssociatorInstancePaths methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenAssociatorInstancePaths operation (see :term:`DSP0200()) and AssociatorNames() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open… function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open… on other pull operation types the first time each type is used.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Otherwise, this method raises an exception.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • AssocClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • ResultClass (string or CIMClassName) –

    Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • ResultRole (string) –

    Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.

    None means that no such filtering is peformed.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation because the act of the server filtering requires that it generate instances and then discard them.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
    • The default is defined as a system config variable.
    • None is not allowed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises:

Exceptions described in WBEMConnection.

Example:

insts_iterator = conn.IterAssociatorInstancePaths('CIM_Blah')
for inst in insts_iterator:
    # close if a particular property value found
    if inst.get('thisPropertyName') == 0
        insts_iterator.close()
        break
    else:
        print('instance %s' % inst.tomof())
IterAssociatorInstances(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple Associators/OpenAssociatorInstance methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenAssociatorInstances() and PullInstancesWithPath() operations (pull operations) or the Associators() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open… function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open… on other pull operation types the first time each type is used.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Parameters:
  • InstanceName (CIMInstanceName) –
    The instance path of the source instance.
    If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
    AssocClass (string or CIMClassName):
    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • ResultClass (string or CIMClassName) –

    Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • ResultRole (string) –

    Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.

    None means that no such filtering is peformed.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instances (or classes), as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string) –

    An iterable specifying the names of the properties to be included in the returned instances (or classes) (case independent). An empty iterable indicates to include no properties.

    If None, all properties are included.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
    • The default is defined as a system config variable.
    • None is not allowed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises:

Exceptions described in WBEMConnection.

Example:

insts_iterator = conn.IterAssociatorInstances('CIM_Blah.key=1',...)
for inst in insts_iterator:
    # close if a particular property value found
    if inst.get('thisPropertyName') == 0
        insts_iterator.close()
        break
    else:
        print('instance %s' % inst.tomof())
IterQueryInstances(FilterQueryLanguage, FilterQuery, namespace=None, ReturnQueryResultClass=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]

A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple ExecQuery/OpenQueryInstances methods and reduces the enumeration to a pythonic iterator idiom.

Experimental: This method is experimental in this release.

This method performs either the OpenQueryInstances() and PullInstances() operations (pull operations) or the ExecQuery() operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.

The use_pull_operations argument of the WBEMConnection constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.

NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open… function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open… on other pull operation types the first time each type is used.

This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:

  • The filter function does not exist for EnumerateInstances so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
  • If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.

An open request may be closed while the iteration process is being executed by issuing the iterator close() method.

If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.

Otherwise, this method raises an exception.

Parameters:
  • QueryLanguage (string) – Name of the query language used in the Query parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. “DMTF:FQL” is not a valid query language for this request.
  • Query (string) – Query string in the query language specified in the QueryLanguage parameter.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the default namespace of the connection object will be used.

  • ReturnQueryResultClass (bool) – Controls whether a class definition is returned.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
    • The default is defined as a system config variable.
    • None is not allowed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A Python:term:generator object. Instances can be retrieved by iterating through the object. An Instance of the nexted class IterQueryInstancesReturn that contains two properties:

query_result_class: If a result class was requested from by the call to InterQueryInstances and one was returned, the CIMClass representing this class is returned. Otherwise, None is returned

generator: That defines a generator for the instances returned from whichever lower level function is called. The instances are accessed using this generator (ex. for inst in rtn.generator:)
Raises:

Exceptions described in WBEMConnection.

Example:

result = conn.IterQueryInstances('DMTF:CQL',
    'SELECT FROM * where pl > 2')
for inst in result.generator:
    print('instance %s' % inst.tomof())
Raises:Exceptions described in WBEMConnection.
OpenEnumerateInstancePaths(ClassName, namespace=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.

This method performs the OpenEnumerateInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns status on the enumeration session and optionally instance paths. Otherwise, this method raises an exception.

Use PullInstancePaths() request to retrieve the next set of instance paths or the CloseEnumeration() request to close the enumeration session early.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be enumerated (case independent). If specified as a CIMClassName object, its namespace attribute will be used as a default namespace as described for the namespace parameter, and its host attribute will be ignored.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation (i.e. return the CIM_ERR_NOT_SUPPORTED exception when filtering is specified) because the act of the server filtering requires that it generate instances and then discard them.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • paths (list of CIMInstanceName): Representations of the initial set of enumerated instance paths, with their attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
OpenEnumerateInstances(ClassName, namespace=None, LocalOnly=None, DeepInheritance=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to get instances of a class (including instances of its subclasses).

This method performs the OpenEnumerateInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.

Use PullInstances() request to retrieve the next set of instance paths or the CloseEnumeration() request to close the enumeration session early.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be enumerated (case independent). If specified as a CIMClassName object, its namespace attribute will be used as a default namespace as described for the namespace parameter, and its host attribute will be ignored.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • LocalOnly (bool) –

    Controls the exclusion of inherited properties from the returned instances, as follows:

    • If False, inherited properties are not excluded.
    • If True, inherited properties are basically excluded, but the behavior may be WBEM server specific.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    This parameter has been deprecated in DSP0200 and should be set to False by the caller.

  • DeepInheritance (bool) –

    Indicates that properties added by subclasses of the specified class are to be included in the returned instances, as follows:

    • If False, properties added by subclasses are not included.
    • If True, properties added by subclasses are included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    Note, the semantics of the DeepInheritance parameter in EnumerateClasses() and EnumerateClassNames() is different.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instance, as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property in the returned instances, as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string) –

    An iterable specifying the names of the properties to be included in the returned instances (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • instances (list of CIMInstance): Representations of the initial set of enumerated instances.

    The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
OpenReferenceInstancePaths(InstanceName, ResultClass=None, Role=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to retrieve the instance paths of the association instances that reference a source instance.

This method does not support retrieving classes.

This method performs the OpenReferenceInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instance paths. Otherwise, this method raises an exception.

Use PullInstances() request to retrieve the next set of instance paths or the CloseEnumeration() request to close the enumeration session early.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • ResultClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation because the act of the server filtering requires that it generate instances and then discard them.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • paths (list of CIMInstanceName): Representations of the initial set of enumerated instance paths, with their attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
OpenReferenceInstances(InstanceName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to retrieve the association instances that reference a source instance.

This method does not support retrieving classes.

This method performs the OpenReferenceInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.

Use PullInstances() request to retrieve the next set of instance paths or the CloseEnumeration() request to close the enumeration session early.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • ResultClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instances (or classes), as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • instances (list of CIMInstance): Representations of the initial set of enumerated instances.

    The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
OpenAssociatorInstancePaths(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to retrieve the instance paths of the instances associated to a source instance.

This method does not support retrieving classes.

This method performs the OpenAssociatorInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instance paths. Otherwise, this method raises an exception.

Use PullInstancePaths() request to retrieve the next set of instance paths or the CloseEnumeration() request to close the enumeration session early.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • AssocClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • ResultClass (string or CIMClassName) –

    Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • ResultRole (string) –

    Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.

    None means that no such filtering is peformed.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation (i.e. return the CIM_ERR_NOT_SUPPORTED exception when filtering is specified) because the act of the server filtering requires that it generate instances and then discard them.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • paths (list of CIMInstanceName): Representations of the initial set of enumerated instance paths, with their attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
OpenAssociatorInstances(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to retrieve the instances associated to a source instance.

This method does not support retrieving classes.

This method performs the OpenAssociatorInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.

The subsequent operation after this open is successful and result.eos = False must be either the PullInstances() request or the CloseEnumeration() request.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • AssocClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • ResultClass (string or CIMClassName) –

    Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • ResultRole (string) –

    Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.

    None means that no such filtering is peformed.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instances (or classes), as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.

  • FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
  • FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • instances (list of CIMInstance): Representations of the initial set of enumerated instances.

    The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
OpenQueryInstances(FilterQueryLanguage, FilterQuery, namespace=None, ReturnQueryResultClass=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]

Open an enumeration session to execute a query in a namespace.

This method performs the OpenQueryInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally CIM instances representing the query result. Otherwise, this method raises an exception.

The subsequent operation after this open is successful and result.eos is False, must be either the PullInstances() request or the CloseEnumeration() request.

Parameters:
  • FilterQueryLanguage (string) – Name of the query language used in the Query parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. “DMTF:FQL” is not a valid query language for this request.
  • FilterQuery (string) – Query string in the query language specified in the QueryLanguage parameter.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the default namespace of the connection object will be used.

  • ReturnQueryResultClass (bool) – Controls whether a class definition is returned.
  • OperationTimeout (Uint32) –

    Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.

    • If not None, this parameter is sent to the WBEM server as the proposed timeout for the enumeration session. A value of 0 indicates that the server is expected to never time out. The server may reject the proposed value, causing a CIMError to be raised with status code CIM_ERR_INVALID_OPERATION_TIMEOUT.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default timeout to be used.
  • ContinueOnError (bool) –

    Indicates to the WBEM server to continue sending responses after an error response has been sent.

    • If True, the server is to continue sending responses after sending an error response. Not all servers support continuation on error; a server that does not support it must send an error response if True was specified, causing CIMError to be raised with status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED.
    • If False, the server is requested to close the enumeration after sending an error response.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is False.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server may return for this request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to leave the handling of any returned instances to a loop of Pull operations.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • instances (list of CIMInstance): Representations of the initial set of enumerated instances.

    The path attribute of each CIMInstance object is None, because query results are not addressable CIM instances.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: The inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.

  • query_result_class (CIMClass): If the ReturnQueryResultClass parameter is True, this tuple item contains a class definition that defines the properties of each row (instance) of the query result. Otherwise, None.
Raises:

Exceptions described in WBEMConnection.
PullInstancesWithPath(context, MaxObjectCount, **extra)[source]

Retrieve the next set of instances with path from an open enumeraton session defined by the enumeration_context parameter. The retrieved instances include their instance paths.

This method performs the PullInstancesWithPath operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.

Parameters:
  • context (string) –

    Identifies the enumeration session, including its current enumeration state. This must be the value of the context item in the namedtuple object returned from the previous open or pull operation for this enumeration.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace to be used for this operation.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server shall return for this request. This parameter is required for each Pull request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to reset the interoperation timer
    • None is not allowed for this operation.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • instances (list of CIMInstance): Representations of the next set of enumerated instances.

    The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
PullInstancePaths(context, MaxObjectCount, **extra)[source]

Retrieve the next set of instance paths from an open enumeraton session defined by the enumeration_context parameter.

This method performs the PullInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instance paths. Otherwise, this method raises an exception.

Parameters:
  • context (string) –

    Identifies the enumeration session, including its current enumeration state. This must be the value of the context item in the namedtuple object returned from the previous open or pull operation for this enumeration.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace to be used for this operation.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server shall return for this request. This parameter is required for each Pull request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to reset the interoperation timer.
    • None is not allowed for this operation.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • paths (list of CIMInstanceName): Representations of the next set of enumerated instance paths, with their attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
PullInstances(context, MaxObjectCount, **extra)[source]

Retrieve the next set of instances from an open enumeraton session defined by the enumeration_context parameter.

This method performs the PullInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.

Parameters:
  • context (string) –

    Identifies the enumeration session, including its current enumeration state. This must be the value of the context item in the namedtuple object returned from the previous open or pull operation for this enumeration.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace to be used for this operation.
  • MaxObjectCount (Uint32) –

    Maximum number of instances the WBEM server shall return for this request. This parameter is required for each Pull request.

    • If positive, the WBEM server is to return no more than the specified number of instances.
    • If zero, the WBEM server is to return no instances. This may be used by a client to reset the interoperation timer.
    • None is not allowed for this operation.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A namedtuple object containing the following named items:

  • instances (list of CIMInstance): Representations of the next set of enumerated instances.

    The path attribute of each CIMInstance object is None, because this operation does not return instance paths.

  • eos (bool): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.

    • If True, the enumeration session is exhausted, and the server has closed the enumeration session.
    • If False, the enumeration session is not exhausted.

  • context (tuple() of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.

    The tuple items are:

    • server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
    • namespace (string): Name of the CIM namespace that was used for this operation.

    NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises:

Exceptions described in WBEMConnection.
CloseEnumeration(context, **extra)[source]

The CloseEnumeration closes an open enumeration session, performing an early termination of an incomplete enumeration session.

This method performs the CloseEnumeration operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

This method should not used if the enumeration session has terminated and will result in an exception response.

If the operation succeeds, this method returns. Otherwise, it raises an exception.

Parameters:context (string) – The enumeration_context paramater must contain the Context value returned by the WBEM server with the response to the previous open or pull operation for this enumeration sequence.
Keyword Arguments:
 extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:Exceptions described in WBEMConnection.
GetInstance(InstanceName, LocalOnly=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]

Retrieve an instance.

This method performs the GetInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • InstanceName (CIMInstanceName) – The instance path of the instance to be retrieved. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
  • LocalOnly (bool) –

    Controls the exclusion of inherited properties from the returned instance, as follows:

    • If False, inherited properties are not excluded.
    • If True, inherited properties are basically excluded, but the behavior may be WBEM server specific.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    This parameter has been deprecated in DSP0200 and should be set to False by the caller.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instance, as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property in the returned instance, as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instance (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A CIMInstance object that is a representation of the retrieved instance. Its path attribute is a CIMInstanceName object with its attributes set as follows:

  • classname: Name of the creation class of the instance.
  • keybindings: Keybindings of the instance.
  • namespace: Name of the CIM namespace containing the instance.
  • host: None, indicating the WBEM server is unspecified.
Raises:

Exceptions described in WBEMConnection.
ModifyInstance(ModifiedInstance, IncludeQualifiers=None, PropertyList=None, **extra)[source]

Modify the property values of an instance.

This method performs the ModifyInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ModifiedInstance (CIMInstance) –

    A representation of the modified instance, also indicating its instance path.

    The path attribute of this object identifies the instance to be modified. Its keybindings attribute is required. If its namespace attribute is None, the default namespace of the connection will be used. Its host attribute will be ignored.

    The classname attribute of the instance path and the classname attribute of the instance must specify the same class name.

    The properties defined in this object specify the new property values for the instance to be modified. Missing properties (relative to the class declaration) and properties provided with a value of None will be set to NULL.

    Typically, this object has been retrieved by other operations, such as GetInstance().

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be modified as specified in the ModifiedInstance parameter, as follows:

    • If False, qualifiers not modified.
    • If True, qualifiers are modified if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be modified (case independent).

    An empty iterable indicates to modify no properties.

    If None, all properties are modified.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
CreateInstance(NewInstance, namespace=None, **extra)[source]

Create an instance in a namespace.

This method performs the CreateInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

The creation class for the new instance is taken from the classname attribute of the NewInstance parameter.

The namespace for the new instance is taken from these sources, in decreasing order of priority:

  • namespace parameter of this method, if not None,
  • namespace in path attribute of the NewInstance parameter, if not None,
  • default namespace of the connection.
Parameters:
  • NewInstance (CIMInstance) –

    A representation of the CIM instance to be created.

    The classname attribute of this object specifies the creation class for the new instance.

    Apart from utilizing its namespace, the path attribute is ignored.

    The properties attribute of this object specifies initial property values for the new CIM instance.

    Instance-level qualifiers have been deprecated in CIM, so any qualifier values specified using the qualifiers attribute of this object will be ignored.

  • namespace (string) – Name of the CIM namespace to be used (case independent).
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A CIMInstanceName object that is the instance path of the new instance.
Raises:

Exceptions described in WBEMConnection.
DeleteInstance(InstanceName, **extra)[source]

Delete an instance.

This method performs the DeleteInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:InstanceName (CIMInstanceName) – The instance path of the instance to be deleted. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
Keyword Arguments:
 extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:Exceptions described in WBEMConnection.
AssociatorNames(ObjectName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, **extra)[source]

Retrieve the instance paths of the instances associated to a source instance.

Retrieve the class paths of the classes associated to a source class.

This method performs the AssociatorNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ObjectName –

    The object path of the source object, as follows:

    • For instance-level usage: The instance path of the source instance, as a CIMInstanceName object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
    • For class-level usage: The class path of the source class, as a string or CIMClassName object:

      If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).

      If specified as a CIMClassName object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.

  • AssocClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • ResultClass (string or CIMClassName) –

    Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • ResultRole (string) –

    Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.

    None means that no such filtering is peformed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

The returned list of objects depend on the usage:

  • For instance-level usage: A list of CIMInstanceName objects that are the instance paths of the associated instances, with their attributes set as follows:
    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
  • For class-level usage: A list of CIMClassName objects that are the class paths of the associated classes, with their attributes set as follows:
    • classname: Name of the class.
    • namespace: Name of the CIM namespace containing the class.
    • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
Raises:

Exceptions described in WBEMConnection.
Associators(ObjectName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]

Retrieve the instances associated to a source instance.

Retrieve the classes associated to a source class.

This method performs the Associators operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ObjectName –

    The object path of the source object, as follows:

    • For instance-level usage: The instance path of the source instance, as a CIMInstanceName object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
    • For class-level usage: The class path of the source class, as a string or CIMClassName object:

      If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).

      If specified as a CIMClassName object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.

  • AssocClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • ResultClass (string or CIMClassName) –

    Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • ResultRole (string) –

    Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.

    None means that no such filtering is peformed.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instances (or classes), as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (or classes) (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

The returned list of objects depend on the usage:

  • For instance-level usage: A list of CIMInstance objects that are representations of the associated instances.

    The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.

  • For class-level usage: A list of tuple() of (classpath, class) objects that are representations of the associated classes.

    Each tuple represents one class and has these items:

    • classpath (CIMClassName): The class path of the class, with its attributes set as follows:
      • classname: Name of the class.
      • namespace: Name of the CIM namespace containing the class.
      • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
    • class (CIMClass): The representation of the class, with its path attribute set to the classpath tuple item.
Raises:

Exceptions described in WBEMConnection.
ReferenceNames(ObjectName, ResultClass=None, Role=None, **extra)[source]

Retrieve the instance paths of the association instances that reference a source instance.

Retrieve the class paths of the association classes that reference a source class.

This method performs the ReferenceNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ObjectName –

    The object path of the source object, as follows:

    • For instance-level usage: The instance path of the source instance, as a CIMInstanceName object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
    • For class-level usage: The class path of the source class, as a string or CIMClassName object:

      If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).

      If specified as a CIMClassName object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.

  • ResultClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

The returned list of objects depend on the usage:

  • For instance-level usage: A list of CIMInstanceName objects that are the instance paths of the referencing association instances, with their attributes set as follows:
    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
  • For class-level usage: A list of CIMClassName objects that are the class paths of the referencing association classes, with their attributes set as follows:
    • classname: Name of the class.
    • namespace: Name of the CIM namespace containing the class.
    • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
Raises:

Exceptions described in WBEMConnection.
References(ObjectName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]

Retrieve the association instances that reference a source instance.

Retrieve the association classes that reference a source class.

This method performs the References operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ObjectName –

    The object path of the source object, as follows:

    • For instance-level usage: The instance path of the source instance, as a CIMInstanceName object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
    • For class-level usage: The class path of the source class, as a string or CIMClassName object:

      If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).

      If specified as a CIMClassName object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.

  • ResultClass (string or CIMClassName) –

    Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).

    None means that no such filtering is peformed.

  • Role (string) –

    Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.

    None means that no such filtering is peformed.

  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned instances (or classes), as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included if the WBEM server implements support for this parameter.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.

  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (or classes) (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

The returned list of objects depend on the usage:

  • For instance-level usage: A list of CIMInstance objects that are representations of the referencing association instances.

    The path attribute of each CIMInstance object is a CIMInstanceName object with its attributes set as follows:

    • classname: Name of the creation class of the instance.
    • keybindings: Keybindings of the instance.
    • namespace: Name of the CIM namespace containing the instance.
    • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.

  • For class-level usage: A list of tuple() of (classpath, class) objects that are representations of the referencing association classes.

    Each tuple represents one class and has these items:

    • classpath (CIMClassName): The class path of the class, with its attributes set as follows:
      • classname: Name of the class.
      • namespace: Name of the CIM namespace containing the class.
      • host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
    • class (CIMClass): The representation of the class, with its path attribute set to the classpath tuple item.
Raises:

Exceptions described in WBEMConnection.
InvokeMethod(MethodName, ObjectName, Params=None, **params)[source]

Invoke a method on a target instance or on a target class.

The methods that can be invoked are static and non-static methods defined in a class (also known as extrinsic methods). Static methods can be invoked on instances and on classes. Non-static methods can be invoked only on instances.

This method performs the extrinsic method invocation operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Input parameters for the CIM method can be specified using the Params parameter, and using keyword parameters. The overall list of input parameters is formed from the list of parameters specified in Params (preserving its order), followed by the set of keyword parameters (in any order). There is no checking for duplicate parameter names.

Parameters:
  • MethodName (string) – Name of the method to be invoked (case independent).
  • ObjectName –

    The object path of the target object, as follows:

    • For instance-level usage: The instance path of the target instance, as a CIMInstanceName object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
    • For class-level usage: The class path of the target class, as a string or CIMClassName object:

      If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).

      If specified as a CIMClassName object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.

  • Params (iterable of tuples of name,value) –

    An iterable of input parameters for the CIM method.

    Each iterated item represents a single input parameter for the CIM method and must be a tuple(name, value), with these tuple items:
:keyword : Each keyword parameter represents a single input parameter for the

CIM method, with:

Returns:A tuple() of (returnvalue, outparams), with these tuple items:
  • returnvalue (CIM data type): Return value of the CIM method.
  • outparams (NocaseDict): Dictionary with all provided output parameters of the CIM method, with:
Raises:Exceptions described in WBEMConnection.
ExecQuery(QueryLanguage, Query, namespace=None, **extra)[source]

Execute a query in a namespace.

This method performs the ExecQuery operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • QueryLanguage (string) – Name of the query language used in the Query parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language.
  • Query (string) – Query string in the query language specified in the QueryLanguage parameter.
  • namespace (string) –

    Name of the CIM namespace to be used (case independent).

    If None, the default namespace of the connection object will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A list of CIMInstance objects that represents the query result.

These instances have their path attribute set to identify their creation class and the target namespace of the query, but they are not addressable instances.
Raises:

Exceptions described in WBEMConnection.
EnumerateClassNames(namespace=None, ClassName=None, DeepInheritance=None, **extra)[source]

Enumerate the names of subclasses of a class, or of the top-level classes in a namespace.

This method performs the EnumerateClassNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • namespace (string) –

    Name of the namespace in which the class names are to be enumerated (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • ClassName (string or CIMClassName) –

    Name of the class whose subclasses are to be retrieved (case independent). If specified as a CIMClassName object, its host attribute will be ignored.

    If None, the top-level classes in the namespace will be retrieved.

  • DeepInheritance (bool) –

    Indicates that all (direct and indirect) subclasses of the specified class or of the top-level classes are to be included in the result, as follows:

    • If False, only direct subclasses of the specified class or only top-level classes are included in the result.
    • If True, all direct and indirect subclasses of the specified class or the top-level classes and all of their direct and indirect subclasses are included in the result.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    Note, the semantics of the DeepInheritance parameter in EnumerateInstances() is different.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A list of unicode string objects that are the class names of the enumerated classes.
Raises:

Exceptions described in WBEMConnection.
EnumerateClasses(namespace=None, ClassName=None, DeepInheritance=None, LocalOnly=None, IncludeQualifiers=None, IncludeClassOrigin=None, **extra)[source]

Enumerate the subclasses of a class, or the top-level classes in a namespace.

This method performs the EnumerateClasses operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • namespace (string) –

    Name of the namespace in which the classes are to be enumerated (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • ClassName (string or CIMClassName) –

    Name of the class whose subclasses are to be retrieved (case independent). If specified as a CIMClassName object, its host attribute will be ignored.

    If None, the top-level classes in the namespace will be retrieved.

  • DeepInheritance (bool) –

    Indicates that all (direct and indirect) subclasses of the specified class or of the top-level classes are to be included in the result, as follows:

    • If False, only direct subclasses of the specified class or only top-level classes are included in the result.
    • If True, all direct and indirect subclasses of the specified class or the top-level classes and all of their direct and indirect subclasses are included in the result.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.

    Note, the semantics of the DeepInheritance parameter in EnumerateInstances() is different.

  • LocalOnly (bool) –

    Indicates that inherited properties, methods, and qualifiers are to be excluded from the returned classes, as follows.

    • If False, inherited elements are not excluded.
    • If True, inherited elements are excluded.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.
  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned classes, as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property and method in the returned classes, as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A list of CIMClass objects that are representations of the enumerated classes, with their path attributes set.
Raises:

Exceptions described in WBEMConnection.
GetClass(ClassName, namespace=None, LocalOnly=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]

Retrieve a class.

This method performs the GetClass operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be retrieved (case independent). If specified as a CIMClassName object, its host attribute will be ignored.
  • namespace (string) –

    Name of the namespace of the class to be retrieved (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.

  • LocalOnly (bool) –

    Indicates that inherited properties, methods, and qualifiers are to be excluded from the returned class, as follows.

    • If False, inherited elements are not excluded.
    • If True, inherited elements are excluded.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.
  • IncludeQualifiers (bool) –

    Indicates that qualifiers are to be included in the returned class, as follows:

    • If False, qualifiers are not included.
    • If True, qualifiers are included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • IncludeClassOrigin (bool) –

    Indicates that class origin information is to be included on each property and method in the returned class, as follows:

    • If False, class origin information is not included.
    • If True, class origin information is included.
    • If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
  • PropertyList (iterable of string or string) –

    An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned class (case independent).

    An empty iterable indicates to include no properties.

    If None, all properties are included.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A CIMClass object that is a representation of the retrieved class, with its path attribute set.
Raises:

Exceptions described in WBEMConnection.
ModifyClass(ModifiedClass, namespace=None, **extra)[source]

Modify a class in a namespace.

This method performs the ModifyClass operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ModifiedClass (CIMClass) –

    A representation of the modified class.

    The properties, methods and qualifiers defined in this object specify what is to be modified.

    Typically, this object has been retrieved by other operations, such as GetClass().

  • namespace (string) –

    Name of the namespace in which the class is to be modified (case independent).

    If None, the default namespace of the connection object will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
CreateClass(NewClass, namespace=None, **extra)[source]

Create a class in a namespace.

This method performs the CreateClass operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • NewClass (CIMClass) –

    A representation of the class to be created.

    The properties, methods and qualifiers defined in this object specify how the class is to be created.

    Its path attribute is ignored.

  • namespace (string) –

    Name of the namespace in which the class is to be created (case independent).

    If None, the default namespace of the connection object will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
DeleteClass(ClassName, namespace=None, **extra)[source]

Delete a class.

This method performs the DeleteClass operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • ClassName (string or CIMClassName) – Name of the class to be deleted (case independent). If specified as a CIMClassName object, its host attribute will be ignored.
  • namespace (string) –

    Name of the namespace of the class to be deleted (case independent).

    If None, the namespace of the ClassName parameter will be used, if specified as a CIMClassName object. If that is also None, the default namespace of the connection will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
EnumerateQualifiers(namespace=None, **extra)[source]

Enumerate qualifier declarations in a namespace.

This method performs the EnumerateQualifiers operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:namespace (string) –

Name of the namespace in which the qualifier declarations are to be enumerated (case independent).

If None, the default namespace of the connection object will be used.
Keyword Arguments:
 extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:A list of CIMQualifierDeclaration objects that are representations of the enumerated qualifier declarations.
Raises:Exceptions described in WBEMConnection.
GetQualifier(QualifierName, namespace=None, **extra)[source]

Retrieve a qualifier declaration in a namespace.

This method performs the GetQualifier operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • QualifierName (string) – Name of the qualifier declaration to be retrieved (case independent).
  • namespace (string) –

    Name of the namespace of the qualifier declaration (case independent).

    If None, the default namespace of the connection object will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns:

A CIMQualifierDeclaration object that is a representation of the retrieved qualifier declaration.
Raises:

Exceptions described in WBEMConnection.
SetQualifier(QualifierDeclaration, namespace=None, **extra)[source]

Create or modify a qualifier declaration in a namespace.

This method performs the SetQualifier operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • QualifierDeclaration (CIMQualifierDeclaration) – Representation of the qualifier declaration to be created or modified.
  • namespace (string) –

    Name of the namespace in which the qualifier declaration is to be created or modified (case independent).

    If None, the default namespace of the connection object will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.
DeleteQualifier(QualifierName, namespace=None, **extra)[source]

Delete a qualifier declaration in a namespace.

This method performs the DeleteQualifier operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.

If the operation succeeds, this method returns. Otherwise, this method raises an exception.

Parameters:
  • QualifierName (string) – Name of the qualifier declaration to be deleted (case independent).
  • namespace (string) –

    Name of the namespace in which the qualifier declaration is to be deleted (case independent).

    If None, the default namespace of the connection object will be used.
Keyword Arguments:
 

extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises:

Exceptions described in WBEMConnection.

4.1.2. WBEM Operation recording

The WBEM client library API provides the possibility to record the WBEM operations that are executed on a connection. WBEM Operation recording uses the classes and subclasses defined in WBEM Operation recorder.

This is disabled by default and can be enabled by adding recorders to a WBEMConnection with the method add_operation_recorder().

Typical usage scenarios for various operation recorders are the tracing of WBEM operations, tracing of interactions with a WBEM server, or the generation of test cases.

Please not that the method of activating operation recorders changed starting with pywbem 0.11.0 and the addition of a second recorder. See add_operation_recorder() for more information.

This adds the recorder defined in the method call to a list of active recorders in WBEMConnection. All active recorders are called for each WBEMConnection method that sends information to the WBEM server.

A single recorder can be be disabled with disable() method and enabled with enable() method.

The logger names for the operations and http loggers must be defined using the :class:~pywbem.`PywbemLoggers` class to define usable loggers because the pywbem loggers include logging attributes in addition to the standard python logger attributes. This is done with the method create_logger() which defines one or more loggers from the input parameters. There is also a convience method create_loggers() which will define multiple pywbem logger definitions from a string definition that could be used with command line tools.

The following example shows defining loggers for both http and operations and adding activating the LogOperationRecorder in WBEMConnection.

# set the python logger facility to output at the DEBUG level
logger.setLevel(logging.DEBUG)

# Define the parameters of the LogOperationRecorder
# using one of the methods in the PywbemLoggers class
PywbemLoggers.create_logger('all',
                            log_dest='file',
                            log_detail_level='min'
                            log_filename='test.log')   # define both loggers

# Create the connection and enable the logger
conn = WBEMConnection(...)
conn.add_operation_recorder(LogOperationRecorder())
# The LogOperationRecorder is now active and writing logs to stderr.

The following example activates and enables both recorders:

# To add both recorders
logger.setLevel(logging.DEBUG)
PywbemLoggers.create_logger('log')   # define only the log logger
conn = WBEMConnection(...)
log_recorder = LogOperationRecorder()
conn.add_operation_recorder(log_recorder)
yamlfp = TestClientRecorder.open_file(self.yamlfile, 'a')
conn.add_operation_recorder(TestClientRecorder(yamlfp))

# Both TestClientRecorder and LogOperationRecorder are be
# active, enabled and recording
# To change the enabled state of either recorder, use the enabled/disabled
# methods of the Recorder
log_recorder.disable()   # disables recording to the log

Activated loggers can be computing-wise expensive so it is best not to activate either logger unless they are to be used for that specific WBEMConnection.

The enable() and disable() methods simply set flags to bypass creating the final recorder output so activating and disabling is still more compute-wise expensive than not activating a recorder at all.

The LogOperationRecorder is a more complete mechanism than the debug in that it records information on operations and HTTP interactions with a WBEM server to a log destination defined through PywbemLoggers using the python logging facility. This information includes the following:

  1. If operations logging is set (the log component == ‘ops’):
    1. Records the method input parameters
    2. Records either all or a fixed length of the response values with an optional maximum length attribute because this log entry can become enormous if it records complete responses.
    3. Records all exceptions
  2. If http logging is set (the log component == ‘http’):
    1. Records the HTTP attributes and data of the request
    2. Records the HTTP attributes and data of the response with an optional max length
  1. If the log component = ‘all’ both operations and http are logged.

In addition to the method and HTTP information, the parameters of each WBEM connection are also logged including an id so that method logs can be linked back to the WBEM connection.

The PywbemLoggers allows defining loggers to output the logs to either stderr or a file based on the create_logger() log_dest parameter.

4.2. CIM objects

CIM objects are local representations of CIM instances, classes, properties, etc., as Python objects. They are used as input to and output from WBEM operations:

CIM object Purpose
CIMInstanceName Instance path of a CIM instance
CIMInstance CIM instance
CIMClassName Name of a CIM class, optionally with class path
CIMClass CIM class
CIMProperty CIM property, both as property value in a CIM instance and as property declaration in a CIM class
CIMMethod CIM method declaration in a CIM class
CIMParameter CIM parameter in a CIM method declaration in a CIM class
CIMQualifier CIM qualifier value
CIMQualifierDeclaration CIM qualifier type/declaration

4.2.1. NocaseDict

NocaseDict is a dictionary implementation with case-insensitive but case-preserving keys. It is used for sets of named CIM elements (e.g. CIM properties in an instance or class, or CIM parameters in a method).

Except for the case-insensitivity of its keys, it behaves like the built-in dict. Therefore, NocaseDict is not described in detail in this documentation.

Deprecated: In v0.9.0, support for comparing two NocaseDict instances with the >, >, <=, >= operators has been deprecated.

4.2.2. CIMInstanceName

class pywbem.CIMInstanceName(classname, keybindings=None, host=None, namespace=None)[source]

A CIM instance path (aka instance name).

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

This object can be used like a dictionary of the keybindings of the instance path, with the names of the keybindings (= key properties) as dictionary keys, and their property values as dictionary values.

Variables:
  • classname (unicode string) –

    Name of the creation class of the referenced instance.

    This variable will never be None.

  • keybindings (NocaseDict) –

    Keybindings of the instance path (the key property values of the referenced instance).

    Each dictionary item specifies one key property value, with:

    This variable will never be None.

  • namespace (unicode string) –

    Name of the CIM namespace containing the referenced instance.

    None means that the namespace is unspecified.

  • host (unicode string) –

    Host and optionally port of the WBEM server containing the CIM namespace of the referenced instance, in the format:

    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.

    If no port is specified, the default port depends on the context in which the object is used.

    None means that the WBEM server is unspecified.
Parameters:
  • classname (string) –

    Name of the creation class of the referenced instance.

    Must not be None.

  • keybindings (dict or NocaseDict) –

    Keybindings for the instance path (the key property values of the referenced instance).

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

  • host (string) –

    Host and optionally port of the WBEM server containing the CIM namespace of the referenced instance.

    For details about the string format, see the corresponding instance variable.

    None means that the WBEM server is unspecified.

  • namespace (string) –

    Name of the CIM namespace containing the referenced instance.

    None means that the namespace is unspecified.
__str__()[source]

Return the untyped WBEM URI of the CIM instance path represented by the CIMInstanceName object.

The returned WBEM URI is consistent with DSP0207.

The key properties in the returned WBEM URI will be ordered by their names.

__repr__()[source]

Return a string representation of the CIMInstanceName object that is suitable for debugging.

The key bindings will be ordered by their names in the result.

copy()[source]

Return a copy of the CIMInstanceName object.

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

Add the positional arguments and keyword arguments to the keybindings, updating the values of those that already exist.

has_key(key)[source]

Return a boolean indicating whether the instance path has a keybinding with name key.

get(key, default=None)[source]

Return the value of the keybinding with name key, or a default value if a keybinding with that name does not exist.

keys()[source]

Return a copied list of the keybinding names (in their original lexical case).

values()[source]

Return a copied list of the keybinding values.

items()[source]

Return a copied list of the keybindings, where each item is a tuple of its keybinding name (in the original lexical case) and its value.

iterkeys()[source]

Iterate through the keybinding names (in their original lexical case).i

itervalues()[source]

Iterate through the keybinding values.

iteritems()[source]

Iterate through the keybindings, where each item is a tuple of the keybinding name (in the original lexical case) and the keybinding value.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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

4.2.3. CIMInstance

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

A CIM instance, optionally including its instance path.

This object can be used like a dictionary of its properties, with the names of the properties as dictionary keys, and their values as dictionary values.

Variables:
  • classname (unicode string) –

    Name of the creation class of the instance.

    This variable will never be None.

  • properties (NocaseDict) –

    Properties for the instance.

    Each dictionary item specifies one property value, with:

    This variable will never be None.

  • qualifiers (NocaseDict) –

    Qualifiers for the instance.

    Each dictionary item specifies one qualifier value, with:

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

    This variable will never be None.

  • path (CIMInstanceName) –

    Instance path of the instance.

    None means that the instance path is unspecified.

  • property_list (list of unicode string) –

    List of property names for use as a filter by some operations on the instance.

    None means that the properties are not filtered.
Parameters:
  • classname (string) – Name of the creation class of the instance. Must not be None.
  • properties (dict or NocaseDict) –

    Properties for the instance.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

  • qualifiers (dict or NocaseDict) –

    Qualifiers for the instance.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

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

  • path (CIMInstanceName) –

    Instance path for the instance.

    None means that the instance path is unspecified.

  • property_list (iterable of string) –

    List of property names for use as a filter by some operations on the instance.

    None means that the properties are not filtered.
__str__()[source]

Return a short string representation of the CIMInstance object for human consumption.

__repr__()[source]

Return a string representation of the CIMInstance object that is suitable for debugging.

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

copy()[source]

Return copy of the CIMInstance object.

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

Add the positional arguments and keyword arguments to the properties, updating the values of those that already exist.

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

Update the values of already existing properties from the positional arguments and keyword arguments.

has_key(key)[source]

Return a boolean indicating whether the instance has a property with name key.

get(key, default=None)[source]

Return the value of the property with name key, or a default value if a property with that name does not exist.

keys()[source]

Return a copied list of the property names (in their original lexical case).

values()[source]

Return a copied list of the property values.

items()[source]

Return a copied list of the properties, where each item is a tuple of the property name (in the original lexical case) and the property value.

iterkeys()[source]

Iterate through the property names (in their original lexical case).

itervalues()[source]

Iterate through the property values.

iteritems()[source]

Iterate through the property names (in their original lexical case).

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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)[source]

Return a unicode string that is a MOF fragment with the instance specification represented by the CIMInstance object.

Parameters:indent (integer) – Number of spaces the initial line of the output is indented.

4.2.4. CIMClassName

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

A CIM class path.

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

Variables:
  • classname (unicode string) –

    Name of the referenced class.

    This variable will never be None.

  • namespace (unicode string) –

    Name of the CIM namespace containing the referenced class.

    None means that the namespace is unspecified.

  • host (unicode string) –

    Host and optionally port of the WBEM server containing the CIM namespace of the referenced class, in the format:

    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.

    If no port is specified, the default port depends on the context in which the object is used.

    None means that the WBEM server is unspecified.
Parameters:
  • classname (string) –

    Name of the referenced class.

    Must not be None.

  • host (string) –

    Host and optionally port of the WBEM server containing the CIM namespace of the referenced class.

    For details about the string format, see the corresponding instance variable.

    None means that the WBEM server is unspecified.

  • namespace (string) –

    Name of the CIM namespace containing the referenced class.

    None means that the namespace is unspecified.
copy()[source]

Return a copy the CIMClassName object.

__str__()[source]

Return the untyped WBEM URI of the CIM class path represented by the CIMClassName object.

The returned WBEM URI is consistent with DSP0207.

__repr__()[source]

Return a string representation of the CIMClassName object that is suitable for debugging.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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.

4.2.5. CIMClass

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

A CIM class, optionally including its class path.

Variables:
  • classname (unicode string) –

    Name of the class.

    This variable will never be None.

  • superclass (unicode string) –

    Name of the superclass of the class.

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

  • properties (NocaseDict) –

    Property declarations of the class.

    Each dictionary item specifies one property declaration, with:

    This variable will never be None.

  • methods (NocaseDict) –

    Method declarations of the class.

    Each dictionary item specifies one method declaration, with:

    This variable will never be None.

  • qualifiers (NocaseDict) –

    Qualifier values of the class.

    Each dictionary item specifies one qualifier value, with:

    This variable will never be None.

  • path (CIMClassName) –

    Class path of the class.

    None means that the class path is unspecified.

    This attribute has been added in pywbem v0.11.0 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.

    This attribute is set in the pywbem client, based on information in the standard response returned by the WBEM server.
Parameters:
  • classname (string) –

    Name for the class.

    Must not be None.

  • properties (dict or NocaseDict) –

    Property declarations for the class.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

  • methods (dict or NocaseDict) –

    Method declarations for the class.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

  • superclass (string) –

    Name of the superclass for the class.

    If None, the class will be a top-level class.

  • qualifiers (dict or NocaseDict) –

    Qualifier values for the class.

    For details about the dictionary items, see the corresponding attribute.

    If None, the class will have no qualifiers.

  • path (CIMClassName) –

    Class path for the class.

    None means that the class path will be unspecified.
__str__()[source]

Return a short string representation of the CIMClass object for human consumption.

__repr__()[source]

Return a string representation of the CIMClass object that is suitable for debugging.

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

copy()[source]

Return a copy of the CIMClass object.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

The path attribute of this object will not be included in the returned CIM-XML representation.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

The path attribute of this object will not be included in the returned CIM-XML representation.

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()[source]

Return a unicode string that is a MOF fragment with the class definition represented by the CIMClass object.

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

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

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.

Variables:
  • name (unicode string) –

    Name of the property.

    This variable will never be None.

  • value (CIM data type) –

    Value of the property (interpreted as actual value when representing a property value, and as default value for property declarations).

    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 in the constructor.

  • type (unicode string) –

    Name of the CIM data type of the property (e.g. "uint8").

    This variable will never be None.

  • reference_class (unicode string) –

    The name of the referenced class as declared in the class defining the reference property.

    None, for non-reference properties, or for reference properties if it was not set.

    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.

  • embedded_object (unicode string) –

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

    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.
  • is_array (bool) –

    A boolean indicating whether the property is an array (True) or a scalar (False).

    This variable will never be None.

  • array_size (integer) –

    The size of the array property, for fixed-size arrays.

    None means that the array property has variable size, or that it is not an array.

  • class_origin (unicode 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.

  • propagated (bool) –

    If not None, indicates whether the property declaration has been propagated from a superclass to this class, or the property value has been propagated from the creation class to this instance (the latter is not really used).

    None means that propagation information is not available.

  • qualifiers (NocaseDict) –

    Qualifier values for the property declaration.

    Each dictionary item specifies one qualifier value, with:

    This variable will never be None.

The constructor 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.

  • value (CIM data type) –

    Value of the property (interpreted as actual value when representing a property value, and as default value for property declarations).

    None means that the property is Null.

  • type (string) –

    Name of the CIM data type of the property (e.g. "uint8").

    None means that the parameter is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.

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

  • array_size (integer) –

    The size of the array property, for fixed-size arrays.

    None means that the array property has variable size.

  • propagated (bool) –

    If not None, indicates whether the property declaration has been propagated from a superclass to this class, or the property value has been propagated from the creation class to this instance (the latter is not really used).

    None means that propagation information is not available.

  • is_array (bool) –

    A boolean indicating whether the property is an array (True) or a scalar (False).

    None means that the parameter is unspecified, causing the corresponding attribute to be inferred from the value parameter, and if that is None it defaults to False (scalar).

  • reference_class (string) –

    The name of the referenced class as declared in the class defining the reference property.

    None means that the parameter is unspecified, causing the corresponding attribute to also be None.

    Note: Prior to pywbem v0.11.0, the corresponding attribute was inferred from the creation class name of a referenced instance. This was incorrect and has been fixed in v0.11.0.

  • qualifiers (dict or NocaseDict) –

    Qualifier values for the property declaration.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

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

    In addition, None means that the value is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.

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(...))

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

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

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

# 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_class="MyClass")

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

# an embedded instance property that is Null:
CIMProperty("MyEmbInst", None, embedded_object="instance")
copy()[source]

Return a copy of the CIMProperty object.

__str__()[source]

Return a short string representation of the CIMProperty object for human consumption.

__repr__()[source]

Return a string representation of the CIMProperty object that is suitable for debugging.

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

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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)[source]

Return a string representing the MOF definition of a single property.

Parameters:
  • is_instance (bool) – If True, format as instance MOF. Else, format as class MOF.
  • indent (integer) – Number of spaces to indent the initial line of the generated MOF.

4.2.7. CIMMethod

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

A method declaration in a CIM class.

Variables:
  • name (unicode string) –

    Name of the method.

    This variable will never be None.

  • return_type (unicode string) –

    Name of the CIM data type of the method return type (e.g. "uint32").

    This variable will never be None. Note that void return types of methods are not supported in CIM.

  • class_origin (unicode 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.

  • propagated (bool) –

    If not None, indicates whether the method has been propagated from a superclass to this class.

    None means that propagation information is not available.

  • parameters (NocaseDict) –

    Parameter declarations for the method declaration.

    Each dictionary item specifies one parameter declaration, with:

    This variable will never be None.

  • qualifiers (NocaseDict) –

    Qualifier values for the method declaration.

    Each dictionary item specifies one qualifier value, with:

    This variable will never be None.

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

Parameters:
  • name (string) –

    Name of the method (just the method name, without class name or parenthesis).

    Must not be None.

    Deprecated: This argument has been named methodname before v0.9.0. Using methodname as a named argument still works, but has been deprecated in v0.9.0.

  • return_type (string) –

    Name of the CIM data type of the method return type (e.g. "uint32").

    Must not be None

  • parameters (dict or NocaseDict) –

    Parameter declarations for the method declaration.

    For details about the dictionary items, see the corresponding attribute.

    If None, the method will have no parameters, and the dictionary will be empty.

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

  • propagated (bool) –

    If not None, indicates whether the method has been propagated from a superclass to this class.

    None means that propagation information is not available.

  • qualifiers (dict or NocaseDict) –

    Qualifier values for the method declaration.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.
__str__()[source]

Return a short string representation of the CIMMethod object for human consumption.

__repr__()[source]

Return a string representation of the CIMMethod object that is suitable for debugging.

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

copy()[source]

Return a copy of the CIMMethod object.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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)[source]

Return a unicode string that is a MOF fragment with the method definition represented by the CIMMethod object.

4.2.8. CIMParameter

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

A CIM parameter for a method declaration.

Variables:
  • name (unicode string) –

    Name of the parameter.

    This variable will never be None.

  • type (unicode string) –

    Name of the CIM data type of the parameter (e.g. "uint8").

    This variable will never be None.

  • reference_class (unicode string) –

    The name of the referenced class, for reference parameters.

    None, for non-reference parameters.

  • is_array (bool) –

    A boolean indicating whether the parameter is an array (True) or a scalar (False).

    This variable will never be None.

  • array_size (integer) –

    The size of the array parameter, for fixed-size arrays.

    None means that the array parameter has variable size, or that it is not an array.

  • qualifiers (NocaseDict) –

    Qualifier values of the parameter declaration.

    Each dictionary item specifies one qualifier value, with:

    This variable will never be None.

  • value – Deprecated: Because the object represents a parameter declaration, this attribute does not make any sense. Accessing it will issue a DeprecationWarning.

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

Parameters:
  • name (string) –

    Name of the parameter.

    Must not be None.

  • type (string) –

    Name of the CIM data type of the parameter (e.g. "uint8").

    Must not be None.

  • reference_class (string) –

    Name of the referenced class, for reference parameters.

    None is stored as-is.

  • is_array (bool) –

    A boolean indicating whether the parameter is an array (True) or a scalar (False).

    None is stored as-is.

  • array_size (integer) –

    The size of the array parameter, for fixed-size arrays.

    None means that the array parameter has variable size.

  • qualifiers (dict or NocaseDict) –

    Qualifier values of the parameter declaration.

    For details about the dictionary items, see the corresponding attribute.

    None is interpreted as an empty dictionary.

  • value – Deprecated: Because the object represents a parameter declaration, this parameter does not make any sense. Specifying a value other than None will issue a DeprecationWarning.
value

Return value attribute (Deprecated).

__str__()[source]

Return a short string representation of the CIMParameter object for human consumption.

__repr__()[source]

Return a string representation of the CIMParameter object that is suitable for debugging.

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

copy()[source]

Return a copy of the CIMParameter object.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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)[source]

Return a unicode string that is a MOF fragment with the parameter definition represented by the CIMParameter object.

Parameters:indent (integer) – Number of spaces to indent each parameter

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

Variables:
  • name (unicode string) –

    Name of the qualifier.

    This variable will never be None.

  • value (CIM data type) –

    Value of the 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 in the constructor.

  • type (unicode string) –

    Name of the CIM data type of the qualifier (e.g. "uint8").

    This variable will never be None.

  • propagated (bool) –

    Indicates whether the qualifier value has been propagated from a superclass to this class.

    None means that this information is not available.

  • tosubclass (bool) –

    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.

  • toinstance (bool) –

    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.

  • overridable (bool) –

    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.

  • translatable (bool) –

    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.

The constructor 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.

  • value (CIM data type) –

    Value of the qualifier.

    None means that the qualifier is Null.

  • type (string) –

    Name of the CIM data type of the qualifier (e.g. "uint8").

    None means that the parameter is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.

  • propagated (bool) –

    If not None, specifies whether the qualifier value has been propagated from a superclass to this class.

    None means that this information is not available.

  • overridable (bool) –

    If not None, specifies whether the qualifier value is overridable in subclasses.

    None means that this information is not available.

  • tosubclass (bool) –

    If not None, specifies whether the qualifier value propagates to subclasses.

    None means that this information is not available.

  • toinstance (bool) –

    If not None, specifies whether the qualifier value propagates to instances.

    None means that this information is not available.

    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.
__str__()[source]

Return a short string representation of the CIMQualifier object for human consumption.

__repr__()[source]

Return a string representation of the CIMQualifier object that is suitable for debugging.

copy()[source]

Return a copy of the CIMQualifier object.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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=4)[source]

Return a unicode string that is a MOF fragment with the qualifier value represented by the CIMQualifier object.

Parameters:indent (integer) – Number of spaces to indent the second and subsequent lines of a multi-line result. The first line is not indented.

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

Variables:
  • name (unicode string) –

    Name of the qualifier.

    This variable will never be None.

  • type (unicode string) –

    Name of the CIM data type of the qualifier (e.g. "uint8").

    This variable will never be None.

  • value (CIM data type) –

    Default value of the 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 in the constructor.

  • is_array (bool) –

    A boolean indicating whether the qualifier is an array (True) or a scalar (False).

    This variable will never be None.

  • array_size (integer) –

    The size of the array qualifier, for fixed-size arrays.

    None means that the array qualifier has variable size, or that it is not an array.

  • scopes (NocaseDict) –

    Scopes of the qualifier.

    Each dictionary item specifies one scope value, with:

    • key (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”, “REFERENCE”, “PROPERTY”, “METHOD”, “PARAMETER”, “INDICATION”, and “ANY”. None is interpreted as an empty dictionary.

    This variable will never be None.

  • tosubclass (bool) –

    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.

  • toinstance (bool) –

    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.

  • overridable (bool) –

    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.

  • translatable (bool) –

    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.
Parameters:
  • name (string) –

    Name of the qualifier.

    Must not be None.

  • type (string) –

    Name of the CIM data type of the qualifier (e.g. "uint8").

    Must not be None.

  • value (CIM data type) –

    Default value of the qualifier.

    None means a default value of Null.

  • is_array (bool) –

    A boolean indicating whether the qualifier is an array (True) or a scalar (False).

    Must not be None.

  • array_size (integer) –

    The size of the array qualifier, for fixed-size arrays.

    None means that the array qualifier has variable size.

  • scopes (dict or NocaseDict) –

    Scopes of the qualifier.

    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.

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

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

    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.
__str__()[source]

Return a short string representation of the CIMQualifierDeclaration object for human consumption.

__repr__()[source]

Return a string representation of the CIMQualifierDeclaration object that is suitable for debugging.

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

copy()[source]

Return a copy the CIMQualifierDeclaration object.

tocimxml()[source]

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

The returned CIM-XML representation is consistent with DSP0201.

tocimxmlstr(indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

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()[source]

Return a unicode string that is a MOF fragment with the qualifier type represented by the CIMQualifierDeclaration object.

4.2.11. Conversion functions

This section describes conversion functions that may be useful for purposes such as debugging.

pywbem.tocimxml(value)[source]

Return the CIM-XML representation of the CIM object or CIM data type, as an Element object.

The returned CIM-XML representation is consistent with DSP0201.

Parameters:value (CIM object or CIM data type) – The value.
Returns:The CIM-XML representation of the specified value, as an instance of an appropriate subclass of Element.

The returned CIM-XML representation is consistent with DSP0201.
pywbem.tocimxmlstr(value, indent=None)[source]

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

The returned CIM-XML representation is consistent with DSP0201.

Parameters:
  • value (CIM object or CIM data type) – The CIM object or CIM data type to be converted to CIM-XML.
  • 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.tocimobj(type_, value)[source]

Return a CIM object representing the specified value and type.

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 some others, see description) –

    The value to be represented as a CIM object.

    In addition to the Python types listed in CIM data types, the following Python types are supported for this parameter:

    • None: The returned object will be None.
    • If type_ specifies one of the CIM integer data types:
    • If type_ specifies the CIM boolean data type:
      • string. The string must be 'true' or 'false' in any lexical case
    • If type_ specifies the CIM datetime data type:
    • If type_ specifies the CIM reference data type:
      • string. The string must be an untyped WBEM URI representing an instance path (see DSP0207)
Returns:

A CIM data type object, representing the specified value and type.
Exceptions:
ValueError - Input cannot be converted to defined CIMValue type or
invalid CIMDatatype name.

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

Note that constructors 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 constructor 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.

cimtype = None

The name of the CIM datatype, as a string. See CIM data types for details.

__repr__()[source]

Return a string representation suitable for debugging.

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.

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

datetime

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

None if this object represents a time interval.

timedelta

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

None if this object represents a point in time.

is_interval

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

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.

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.
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.
__str__()[source]

Return a string representing the object in CIM datetime format.

__repr__()[source]

Return a string representation suitable for debugging.

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

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.

class pywbem.CIMInt[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.

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

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.

__repr__()[source]

Return a string representation suitable for debugging.

class pywbem.Uint8[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Sint8[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Uint16[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Sint16[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Uint32[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Sint32[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Uint64[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.Sint64[source]

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

For details on CIM integer data types, see CIMInt.

class pywbem.CIMFloat[source]

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

class pywbem.Real32[source]

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

class pywbem.Real64[source]

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

4.4. 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.
  • Default CIM namespace DEFAULT_NAMESPACE. It is used as a default for the namespace parameter of WBEMConnection.

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_FAILED = 1

A general error occurred that is not covered by a more specific error code.

pywbem.cim_constants.CIM_ERR_ACCESS_DENIED = 2

Access to a CIM resource is not available to the client.

pywbem.cim_constants.CIM_ERR_INVALID_NAMESPACE = 3

The target namespace does not exist.

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_CLASS = 5

The specified class does not exist.

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_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_INVALID_SUPERCLASS = 10

The operation cannot be invoked because the specified superclass does not exist.

pywbem.cim_constants.CIM_ERR_ALREADY_EXISTS = 11

The operation cannot be invoked because an object already exists.

pywbem.cim_constants.CIM_ERR_NO_SUCH_PROPERTY = 12

The specified property does not exist.

pywbem.cim_constants.CIM_ERR_TYPE_MISMATCH = 13

The value supplied is not compatible with the type.

pywbem.cim_constants.CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED = 14

The query language is not recognized or supported.

pywbem.cim_constants.CIM_ERR_INVALID_QUERY = 15

The query is not valid for the specified query language.

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.

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.

pywbem.cim_constants.CIM_ERR_INVALID_OPERATION_TIMEOUT = 22

The specified operation timeout is not supported by the WBEM server.

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.

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.

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.

pywbem.cim_constants.CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED = 26

The WBEM server does not support continuation on error.

pywbem.cim_constants.CIM_ERR_SERVER_LIMITS_EXCEEDED = 27

The WBEM server has failed the operation based upon exceeding server limits.

pywbem.cim_constants.CIM_ERR_SERVER_IS_SHUTTING_DOWN = 28

The WBEM server is shutting down and cannot process the operation.

pywbem.cim_constants.DEFAULT_NAMESPACE = 'root/cimv2'

Default CIM namespace

4.5. Exceptions

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

class pywbem.Error[source]

Base class for pywbem specific exceptions.

class pywbem.ConnectionError[source]

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

class pywbem.AuthError[source]

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

class pywbem.HTTPError(status, reason, cimerror=None, cimdetails=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.

Parameters:
  • status (number) – HTTP status code (e.g. 500).
  • reason (string) – HTTP reason phrase (e.g. ‘Internal Server Error’).
  • cimerror (string) – Value of the CIMError 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.
status

HTTP status code (e.g. 500), as a number.

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

reason

HTTP reason phrase (e.g. ‘Internal Server Error’), as a string.

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

cimerror

Value of CIMError header field in response, if present, as a string. None, otherwise.

See DSP0200 for a list of values.

cimdetails

CIMOM-specific details on the situation reported in the CIMError header field, as a dictionary:

  • Key: header field name (e.g. PGErrorDetail).
  • Value: header field value.
class pywbem.TimeoutError[source]

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

class pywbem.ParseError[source]

This exception indicates a parsing error with the CIM-XML response returned by the WBEM server, or in the CIM-XML request sent by the WBEM listener. Derived from Error.

class pywbem.CIMError(status_code, status_description=None)[source]

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

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

In its version 0.9, pywbem has added the status_code and status_description properties.

With all these variations, the following approach for accessesing the CIM status code a CIMError object works for all pywbem versions since 0.7.0 and for Python 2 and 3:

except CIMError as exc:
    status_code = exc.args[0]

The following approach is recommended when using pywbem 0.9 or newer, and it works for Python 2 and 3:

except CIMError as exc:
    status_code = exc.status_code

The following approach is limited to Python 2 and will not work on Python 3, and is therefore not recommended:

except CIMError as exc:
    status_code = exc[0]
Parameters:
  • status_code (number) – 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.
Variables:

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

Numeric CIM status code.

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

status_code_name

Symbolic name of the CIM status code.

If the CIM status code is invalid, the string "Invalid status code <code>" is returned.

status_description

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

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 <code>" is returned.

Note that args[1] is always the status_description init argument, without defaulting it to a standard text in case of None.

4.6. Statistics

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:

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.

Experimental: The statistics support is experimental for this release.

class pywbem.Statistics(enable=False)[source]

A container class for multiple operation statistic objects (of class OperationStatistic).

Each operation statistic object is identified by a name, that is defined in the start_timer() method.

The statistics container 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. Its enablement state can be controlled via the enable() and disable() methods. Its current enablement state can be accessed via the enabled property.

Experimental: This class is experimental for this release.

Parameters:enable (bool) – Initial enablement status for this statistics container.
enabled

Indicates whether the statistics container is enabled.

enable()[source]

Enable the statistics container.

disable()[source]

Disable the statistics container.

start_timer(name)[source]

Start the timer for a given operation name and return the corresponding OperationStatistic object, creating one if needed.

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
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
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:
__repr__()[source]

Return a human readable display of the contents, for debug purposes.

formatted()[source]

Return a human readable string with the statistics for this container. The operations are sorted by decreasing average time.

Server time statistic is included only if the wbem server has returned statistics information.

Example w/o server times:

Statistics (times in seconds, lengths in Bytes):
Count  Exc            Time                ReqLen                ReplyLen          Operation
       Cnt    Avg     Min     Max    Avg    Min    Max      Avg      Min      Max
    3    0   0.234   0.100   0.401   1233   1000   1500    26667    20000    35000 EnumerateInstances
    1    0   0.100   0.100   0.100   1200   1200   1200    22000    22000    22000 EnumerateInstanceNames
class pywbem.OperationStatistic(container, name)[source]

A statistics data keeper for the executions of all operations with the same operation name.

This class maintains max, min, avg and count for elapsed time, request size, and response size over the executed operations of a single operation name.

Use the pywbem.Statistics.start_timer() method to create objects of this class:

stats = container.start_timer('EnumerateInstances')
...
stats.stop_timer(request_len, reply_len, server_time, exc)

Experimental: This class is experimental for this release.

Parameters:
  • container (Statistics) – The statistics container that holds this operation statistic object.
  • name (string) – Name of the operation.
stat_start_time

float – 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()).

name

string – Name of the operation for which this statistics object maintains data.

This name is used by the Statistics object holding this time statistics as a key.

container

Statistics – The statistics container that holds this statistics object.

count

integer – The number of measured operations (that is, invocations of the stop_timer() method).

exception_count

integer – The number of exceptions that occurred when invoking the measured operations.

avg_time

float – The average elapsed time for invoking the measured operations, in seconds.

min_time

float – The minimum elapsed time for invoking the measured operations, in seconds.

max_time

float – The maximum elapsed time for invoking the measured operations, in seconds.

avg_server_time

float – The average elapsed time for invoking the measured operations, in seconds.

min_server_time

float – The minimum elapsed time for invoking the measured operations, in seconds.

max_server_time

float – The maximum elapsed time for invoking the measured operations, in seconds.

avg_request_len

float – The average size of the HTTP body in the CIM-XML requests of the invoked operations, in Bytes.

min_request_len

float – The minimum size of the HTTP body in the CIM-XML requests of the invoked operations, in Bytes.

max_request_len

float – The maximum size of the HTTP body in the CIM-XML requests of the invoked operations, in Bytes.

avg_reply_len

float – The average size of the HTTP body in the CIM-XML responses of the invoked operations, in Bytes.

min_reply_len

float – The minimum size of the HTTP body in the CIM-XML responses of the invoked operations, in Bytes.

max_reply_len

float – The maximum size of the HTTP body in the CIM-XML responses of the invoked operations, in Bytes.

reset()[source]

Reset the statistics data for this object.

start_timer()[source]

This method needs to be called at the begin of an operation that is intended to be measured. It starts the measurement for that operation (by capturing the current point in time), if the statistics container holding this object is enabled. Otherwise, this method does nothing.

A subsequent invocation of stop_timer() will complete the measurement for that operation and will update the statistics data.

stop_timer(request_len, reply_len, server_time=None, exception=False)[source]

This method needs to be called at the end of an operation that is intended to be measured. It completes the measurement for that operation by capturing the needed data, and updates the statistics data, if the statistics container holding this object is enabled. Otherwise, this method does nothing.

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, there is no time from the server.
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
__repr__()[source]

Return a human readable string with the statistics values, for debug purposes.

formatted_header_w_svr = 'Count Excep Time ServerTime RequestLen ReplyLen Operation\n Cnt Avg Min Max Avg Min Max Avg Min Max Avg Min Max\n'

Formatted header string (two lines), for use with the formatted rows returned by the formatted() method.

For an example, see pywbem.Statistics.formatted().

formatted(include_server_time)[source]

Return a formatted one-line string with the statistics values for this operation.

The returned string can be used with the formatted header string defined in formatted_header.

For an example, see pywbem.Statistics.formatted().

4.7. Logging

The pywbem package implements selected logging based on the Python logging facility.

Pywbem logging is used as a tool to record information passing between the pywbem client and WBEM servers but not as a general recorder for errors, state, etc. within pywbem. 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 supports multiple Logger objects (named loggers). Two named loggers are defined in this code and used by pywbem:

  • pywbem.ops logs user-issued calls to pywbem WBEMConnection methods that drive WBEM operations (see WBEM operations). Log entries are created at INFO log level. This logs the parameters of each request and the CIMObjects/exceptions in each method repoonse.
  • pywbem.http logs HTTP requests and responses between the pywbem client and WBEM servers, at the info level. This logs the http request data and response data. This named logger is also defined to create log entries when logging is at the INFO log level.

To output log records for one of the defined named loggers, either create_loggers() or the create_logger() should be used to define the characteristics of the named logger.

  • create_loggers() creates one or more loggers from a string input that defines the component name and characteristics of each logger. This allows other tools like CLIs that use pywbem to create the pywbem known logs with minimal work from command line or config file input.
  • create_logger() creates one or more loggers from parameter inputs that define the component name and characteristics of each logger.

These functions save the logger definitions in the PywbemLoggers class that is used by the logging functions in the recorder so trying to create the named loggers independently of this code may cause issues.

The pywbem loggers are based on two parameters (log destination, log detail) that determine if the logs for the logger name are created, how much information is inserted, and the log destination. This extends the python logging facility to include the log_detail parameter which defines whether all the information defined or only a limited size is output. This is used with pywbem because the logs on operation and http responses can be very large.

The code that executes the loggers call the function get_logger(..) to get a logger from a defined logger name. If that logger has not yet been defined in PywbemLoggers, an entry will be added with the default parameters.

pywbem._logging.LOG_OPS_CALLS_NAME = 'pywbem.ops'

Name of logger for logging user-issued calls to pywbem WBEMConnection methods functions that drive WBEM operations.

pywbem._logging.LOG_COMPONENTS = ['ops', 'http', 'all']

List of the logger names that class – pywbem.PywbemLoggers recognizes:

pywbem._logging.LOG_DESTINATIONS = ['file', 'stderr', 'none']

List of log destinations that pywbem.PywbemLoggers recognizes.

pywbem._logging.LOG_DETAIL_LEVELS = ['all', 'min']

list of the log detail strings that pywbem.PywbemLoggers recognizes.

pywbem._logging.MAX_LOG_ENTRY_SIZE = 1000

Maximum log entry size. An integer that sets the maximum size of each log entry if the log_detail_level attribute is set to ‘min’ is set.

pywbem._logging.DEFAULT_LOG_DESTINATION = 'none'

DEFAULT log destination is none is defined when named loggers are configured. ‘none’ means that there is no logging.

class pywbem._logging.PywbemLoggers[source]

Container for pywbem logger information when loggers are created. This class is a singleton, there is only one set of data for a pywbem instantiation. Its goal is to defined named loggers from data input and too record information about these named loggers in a dictionary for use by the log functions

This is defined with only class level object and methods as an easy way to create a singleton. However, at least in python 2.6, you cannot make some magic methods work (ex.__getItem__)

There are two constructors for loggers:

create_loggers() - Creates one or more logger entries in this class and also in the python logging class from an input string with the format defined in the create_loggers method below.

create_logger() - Creates a single logger from the separate pywbem logging parameters supplied with the method.

Experimental: The logging support is experimental for this release.

classmethod create_loggers(input_str, log_filename=None)[source]

Create the pywbem loggers defined by the input string in the following syntax and place the logger definitions in the class level dictionary in this class.

Parameters:
  • input_str (string) –

    as follows:

    log_specs := log_spec [, log_spec ]

    log_spec := log_comp [‘=’ [ dest ][“:”[ detail_level ]]]]

    where:
    log_comp: Must be one of strings in the LOG_COMPONENTS list.

    detail_level: Must be one of strings in the LOG_DETAIL_LEVELS list.

    dest: Must be one of strings in the LOG_DESTINATIONS list.

  • log_filename (string) – Optional string that defines the filename for output of logs if the dest type is file
Exceptions:
ValueError - Generated if the syntax of the input string is invalid or any of the components is not one of allowed strings.

Examples

ops=stderr:min # set cim operations logger

http=file: # set http logger to send to file

all=file:all # Set all loggers to default log destination

classmethod create_logger(log_component, log_dest='none', log_filename='none', log_detail_level='min')[source]

Create the logger defined by the input parameters and place the result in a class level dictionary in this class.

This function can be used to set up all of the named loggers used by pywbem.

Parameters:
  • log_component (string) – The name of the logger. It must be one of the names defined in LOG_COMPONENTS. Used to create the logger name by prepending with the logger name prefix pywbem..
  • log_dest (string) – String defining the destination for this log. It must be one of the destinations defined in LOG_DESTINATIONS or None. If the value is none the null logger is created.
  • log_filename (string) – Filename to use as logging file if the log destination is file. Ignored if log destination is not file. If value is None and this is a file log, ValueError is raised.
  • log_detail_level (string) – String defining the level of detail for log output. This is optional. The default is defined in DEFAULT_LOG_DETAIL_LEVEL.
Exceptions:
ValueError - Input contains an invalid log destination, log level, or log detail level. No named logger is configured.
classmethod get_logger_info(logger_name)[source]

Get information about a logger by name.

Parameters:logger_name (string) – The pywbem logger name (ex. pywbem.ops)
Returns:(log_detail_level, log_level, log_dest, log_filename) or ‘None’ if the logger has not been defined to PywbemLoggers
Return type:Tuple with the following information in the tuple
class pywbem.PywbemLoggers[source]

Container for pywbem logger information when loggers are created. This class is a singleton, there is only one set of data for a pywbem instantiation. Its goal is to defined named loggers from data input and too record information about these named loggers in a dictionary for use by the log functions

This is defined with only class level object and methods as an easy way to create a singleton. However, at least in python 2.6, you cannot make some magic methods work (ex.__getItem__)

There are two constructors for loggers:

create_loggers() - Creates one or more logger entries in this class and also in the python logging class from an input string with the format defined in the create_loggers method below.

create_logger() - Creates a single logger from the separate pywbem logging parameters supplied with the method.

Experimental: The logging support is experimental for this release.

classmethod create_loggers(input_str, log_filename=None)[source]

Create the pywbem loggers defined by the input string in the following syntax and place the logger definitions in the class level dictionary in this class.

Parameters:
  • input_str (string) –

    as follows:

    log_specs := log_spec [, log_spec ]

    log_spec := log_comp [‘=’ [ dest ][“:”[ detail_level ]]]]

    where:
    log_comp: Must be one of strings in the LOG_COMPONENTS list.

    detail_level: Must be one of strings in the LOG_DETAIL_LEVELS list.

    dest: Must be one of strings in the LOG_DESTINATIONS list.

  • log_filename (string) – Optional string that defines the filename for output of logs if the dest type is file
Exceptions:
ValueError - Generated if the syntax of the input string is invalid or any of the components is not one of allowed strings.

Examples

ops=stderr:min # set cim operations logger

http=file: # set http logger to send to file

all=file:all # Set all loggers to default log destination

classmethod create_logger(log_component, log_dest='none', log_filename='none', log_detail_level='min')[source]

Create the logger defined by the input parameters and place the result in a class level dictionary in this class.

This function can be used to set up all of the named loggers used by pywbem.

Parameters:
  • log_component (string) – The name of the logger. It must be one of the names defined in LOG_COMPONENTS. Used to create the logger name by prepending with the logger name prefix pywbem..
  • log_dest (string) – String defining the destination for this log. It must be one of the destinations defined in LOG_DESTINATIONS or None. If the value is none the null logger is created.
  • log_filename (string) – Filename to use as logging file if the log destination is file. Ignored if log destination is not file. If value is None and this is a file log, ValueError is raised.
  • log_detail_level (string) – String defining the level of detail for log output. This is optional. The default is defined in DEFAULT_LOG_DETAIL_LEVEL.
Exceptions:
ValueError - Input contains an invalid log destination, log level, or log detail level. No named logger is configured.
classmethod get_logger_info(logger_name)[source]

Get information about a logger by name.

Parameters:logger_name (string) – The pywbem logger name (ex. pywbem.ops)
Returns:(log_detail_level, log_level, log_dest, log_filename) or ‘None’ if the logger has not been defined to PywbemLoggers
Return type:Tuple with the following information in the tuple

4.8. WBEM Operation recorder

The WBEM client library API includes the abstract base class BaseOperationRecorder from which operation recorders can be written that perform specific recording tasks.

Users can write their own operation recorder classes based upon the abstract base class BaseOperationRecorder.

The WBEM client library API provides the following operation recorder classes:

Class Purpose
TestClientRecorder Generate test cases for the test_client unit test module.
LogOperationRecorder Generate logs using the python logging facitlity for WBEMConnection methods that communicate with a WBEM server.
class pywbem.BaseOperationRecorder[source]

Abstract base class defining the interface to an operation recorder, that records the WBEM operations executed in a connection to a WBEM server.

An operation recorder can be registered by setting the operation_recorder instance attribute of the WBEMConnection object to an object of a subclass of this base class.

When an operation recorder is registered on a connection, each operation that is executed on the connection will cause the record() method of the operation recorder object to be called, if the recorder is enabled.

The operation recorder is by default enabled, and can be disabled and re-enabled using the disable() and enable() methods, respectively. This can be used to temporarily pause the recorder.

enable()[source]

Enable the recorder.

disable()[source]

Disable the recorder.

enabled

Indicate whether the recorder is enabled.

static open_file(filename, file_mode='w')[source]

A static convience function that performs the open of the recorder file correctly for different versions of python. This covers the issue where the file should be opened in text mode but that is done differently in python 2 and python 3

Parameters:
  • filename (string) – Name of the file where the recorder output will be written
  • file_mode (string) – Optional file mode. The default is ‘w’ which overwrites any existing file. if ‘a’ is used, the data is appended to any existing file.

Example:

recorder = TestClientRecorder(
    BaseOperationRecorder.open_file('recorder.log'))
reset(pull_op=None)[source]

Reset all the attributes in the class. This also allows setting the pull_op attribute that defines whether the operation is to be a traditional or pull operation. This does NOT reset _conn.id as that exists through the life of the connection.

stage_wbem_connection(wbem_connection)[source]

Stage information about the connection. Used only by LogOperationRecorder.

stage_pywbem_args(method, **kwargs)[source]

Set requst method and all args. Normally called before the cmd is executed to record request parameters

stage_pywbem_result(ret, exc)[source]

Set Result return info or exception info

stage_http_request(conn_id, version, url, target, method, headers, payload)[source]

Set request HTTP information including url, headers, etc.

stage_http_response1(conn_id, version, status, reason, headers)[source]

Set response http info including headers, status, etc. conn_id unused here. Used in log

stage_http_response2(payload)[source]

Stage second part of http response, the payload

record_staged()[source]

Encode staged information on request and result to output

record(pywbem_args, pywbem_result, http_request, http_response)[source]

Function that is called to record a single WBEM operation, i.e. the invocation of a single WBEMConnection method.

This function is called only when the recorder is enabled, i.e. it does not need to check for recorder enablement.

Parameters:
  • pywbem_args (OpArgs) – The name and input arguments of the WBEMConnection method that is recorded.
  • pywbem_result (OpResult) – The result (return value or exception) of the WBEMConnection method that is recorded.
  • http_request (HttpRequest) –

    The HTTP request sent by the WBEMConnection method that is recorded.

    None, if no HTTP request had been sent (e.g. because an exception was raised before getting there).

  • http_response (HttpResponse) –

    The HTTP response received by the WBEMConnection method that is recorded.

    None, if no HTTP response had been received (e.g. because an exception was raised before getting there).
class pywbem.OpArgs[source]

A named tuple representing the name and input arguments of the invocation of a WBEMConnection method, with the following named fields and attributes:

Variables:

Create new instance of OpArgsTuple(method, args)

class pywbem.OpResult[source]

A named tuple representing the result of the invocation of a WBEMConnection method, with the following named fields and attributes:

Variables:
  • ret (object) –

    Return value, if the method returned. None, if the method raised an exception.

    Note that None may be a legitimate return value, so the test for exceptions should be done based upon the exc variable.

  • exc (Exception) – Exception object, if the method raised an exception. None, if the method returned.

Create new instance of OpResultTuple(ret, exc)

class pywbem.HttpRequest[source]

A named tuple representing the HTTP request sent by the WBEM client, with the following named fields and attributes:

Variables:

Create new instance of HttpRequestTuple(version, url, target, method, headers, payload)

class pywbem.HttpResponse[source]

A named tuple representing the HTTP response received by the WBEM client, with the following named fields and attributes:

Variables:
  • version (number) – HTTP version from the response line (10 for HTTP/1.0, 11 for HTTP/1.1).
  • status (number) – HTTP status code from the response line (e.g. 200).
  • reason (unicode string) – HTTP reason phrase from the response line (e.g. “OK”).
  • headers (dict) –

    A dictionary of all HTTP header fields:

  • payload (unicode string) – HTTP payload, i.e. the CIM-XML string.

Create new instance of HttpResponseTuple(version, status, reason, headers, payload)

class pywbem.TestClientRecorder(fp)[source]

An operation recorder that generates test cases for each recorded operation. The test cases are in the YAML format suitable for the test_client unit test module of the pywbem project.

Parameters:fp (file) –

An open file that each test case will be written to. This file should have been opened in text mode.

Since there are differences between python 2 and 3 in opening files in text mode, the static method open_file() can be used to open the file or python 2/3 compatible open:

from io import open
    f = open('blah.log', encoding='utf-8')

Example:

recorder = TestClientRecorder(
    BaseOperationRecorder.open_file('recorder.log'))
record(pywbem_args, pywbem_result, http_request, http_response)[source]

Function that records the invocation of a single WBEMConnection method, by appending a corresponding test case to the file.

Parameters: See pywbem.BaseOperationRecorder.record().

toyaml(obj)[source]

Convert any allowable input argument to or return value from an operation method to an object that is ready for serialization into test_client yaml format.

class pywbem.LogOperationRecorder(max_log_entry_size=None)[source]

An Operation Recorder that logs the information to a set of named logs. This recorder uses two named logs:

LOG_OPS_CALLS_NAME - Logger for cim_operations method calls and responses

LOG_HTTP_NAME - Logger for http_requests and responses

This also implements a method to log information on each connection.

All logging calls are at the debug level.

Creates the the loggers and sets the max_log_size for each if the input parameter max_log_entry_size is not None.

Parameters: (integer)

max_log_entry_size(integer)
The maximum size of each log entry. This is primarily to limit response sizes since they could be enormous. If None, no size limit and the full request or response is logged.
stage_wbem_connection(wbem_connection)[source]

Log connection information. This includes the connection id that should remain throught the life of the connection.

stage_pywbem_args(method, **kwargs)[source]

Log request method and all args. Normally called before the cmd is executed to record request parameters. This method does not limit size of log record.

stage_pywbem_result(ret, exc)[source]

Log result return or exception parameter. This function allows setting maximum size on the result parameter logged because response information can be very large .

stage_http_request(conn_id, version, url, target, method, headers, payload)[source]

Log request HTTP information including url, headers, etc.

stage_http_response1(conn_id, version, status, reason, headers)[source]

Set response http info including headers, status, etc.

stage_http_response2(payload)[source]

Log complete http response, including response1 and payload

record_staged()[source]

Not used for logging

record(pywbem_args, pywbem_result, http_request, http_response)[source]

Not used for logging

4.9. Security considerations

4.9.1. 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 API, 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:

  1. 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.
  2. The use of HTTP Basic Authentication is strongly discouraged, because the password is sent unencrypted over the network.
  3. 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).
  4. 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 API, 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 may specify the location of X.509 CA certificates that are used to validate the X.509 server certificate returned by the WBEM server. If not specified, pywbem assumes default locations for these certificates.

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.

4.9.2. 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 performs the following verifications on the server certificate returned by the WBEM server:

  • Validation of the server certificate against the CA certificates specified in the ca_certs parameter. This is done by the TLS/SSL components used by pywbem.
  • Validation of the server certificate’s expiration date, based on the system clock. This is done by the TLS/SSL components used by pywbem.
  • Validation of the hostname, by comparing the Subject attribute of the server certificate with the hostname specified in the url parameter. This is done by pywbem itself.
  • Calling the validation function specified in the verify_callback parameter, if any, and looking at its validation result.

If any of these validations fails, the WBEM operation methods of the WBEMConnection object raise a pywbem.AuthError.

If verification was disabled via the no_verification parameter, none of these validations of the server certificate happens.

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

4.9.4. Authentication errors

The operation methods of WBEMConnection raise pywbem.AuthError in any of these situations:

  • When client side verification of the X.509 server certificate fails.
  • 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:
    • no authorization information provided by client
    • wrong HTTP authentication scheme used by client
    • authentication failed
    • user is not authorized to access resource

4.9.5. Default CA certificate paths

pywbem.cim_http.DEFAULT_CA_CERT_PATHS = ['/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt', '/etc/ssl/certs', '/etc/ssl/certificates']

Default directory paths for looking up CA certificates for linux.