Pywbem - A WBEM client

Pywbem is a WBEM client, written in pure Python. It supports Python 2 and Python 3.

A WBEM client allows issuing operations to a WBEM server, using the CIM operations over HTTP (CIM-XML) protocol defined in the DMTF standards DSP0200 and DSP0201. The CIM/WBEM infrastructure is used for a wide variety of systems management tasks supported by systems running WBEM servers. See WBEM Standards for more information about WBEM.

This package is based on the idea that a good WBEM client should be easy to use and not necessarily require a large amount of programming knowledge. It is suitable for a large range of tasks from simply poking around to writing web and GUI applications.

The general pywbem web site is: http://pywbem.github.io/pywbem/index.html.

Introduction

Functionality

Pywbem supports the following functionality:

  • WBEM client library API

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

  • WBEM server API

    This API encapsulates certain functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace of the server, or the management profiles advertised by the server.

  • WBEM indication API

    This API supports starting and stopping a WBEM listener that waits for indications (i.e. events) emitted by a WBEM server using the CIM-XML protocol. The API also supports managing subscriptions for such indications.

  • MOF compiler API

    This API provides for invoking the MOF compiler and for plugging in your own CIM repository into the MOF compiler.

  • WBEM utility commands

    Pywbem includes a few utility commands:

    • mof_compiler

      A MOF compiler that takes MOF files as input and creates, updates or removes CIM instances, classes or qualifier types in a CIM repository.

      See DSP0004 for a description of MOF (Managed Object Format).

      By default, the CIM repository used by the MOF compiler is in a WBEM server. The MOF compiler API provides for plugging in your own CIM repository the compiler can work against.

    • wbemcli

      A WBEM command line interface that provides an interactive Python environment for issuing WBEM operations to a WBEM server.

Installation

Pywbem is a pure Python package that can be installed from PyPi or from its repository by the usual means for installing Python packages.

Some of the Python packages used by pywbem have dependencies on operating system packages. As of pywbem v0.8, the setup script has support for installing prerequisite operating system packages via a new install_os command for the setup script. Alternatively, you can establish these prerequisites yourself. For details, see Prerequisite operating system packages.

The following examples show different ways to install pywbem. They all ensure that prerequisite Python packages are installed as needed:

  1. Install the latest released version, assuming the OS-level prerequisites are already established:

    $ pip install pywbem

  2. Install the latest released version and also install (or display) any OS-level prerequisites:

    $ pip download --no-deps --no-binary :all: pywbem
$ tar -xzf pywbem-*.tar.gz

    or, when using pip versions before 8.0.0, you have to know the pywbem version to download:

    $ curl -L https://github.com/pywbem/pywbem/archive/v0.9.0.tar.gz |tar -xz

    Followed in both cases by these commands:

    $ cd pywbem-*
$ python setup.py install_os install

  3. Install a particular branch from the Git repository:

    $ pip install git+https://github.com/pywbem/pywbem.git@<branch-name>

These examples install pywbem and its prerequisite Python packages into the currently active Python environment. By default, the system Python environment is active. This is probably the right choice if you just want to use the scripts that come with pywbem. In that case, you need to prepend the installation commands shown above (i.e. pip and python setup.py) with sudo, and your Linux userid needs to be authorized accordingly. If your intention is to write code against the pywbem APIs, installation into a virtual Python environment is recommended).

The second example installs the OS-level prerequisites always into the system, regardless of whether or not you have a virtual Python environment active. The setup script uses sudo under the covers. This means that you don’t need to take care about that and can use sudo to control whether you install the Python packages into a virtual or system Python environment.

The command syntax above is shown for Linux, but works in similar ways on Windows and OS-X.

In case of trouble with the installation, see the Troubleshooting section.

You can verify that pywbem and its dependent packages are installed correctly by importing the package into Python:

$ python -c "import pywbem; print('ok')"
ok

Prerequisite operating system packages

Prerequisite operating system packages can be installed by the pywbem setup script using a new command install_os:

$ python setup.py install_os

For a number of well-known Linux distributions, the setup script will install the packages using the respective installer program (e.g. yum on RHEL). For other Linux distributions and for non-Linux operating systems, the setup script will display the package names that would be needed on RHEL, leaving it to the user to translate them accordingly.

When installing such packages on Linux, the setup script uses the sudo command, so your userid needs to be authorized accordingly.

This command also downbloads and builds swig and installs its build prerequisites if it cannot be installed as an operating system package in the required version.

The second example in the previous section shows how to use the new setup command install_os. It is really simple to be used and avoids the manual procedure for establishing the operating system packages as described in the remainder of this section.

For manual installation of the prerequisite operating system packages, or for including pywbem in distributions, the following table lists the packages and their version requirements for a number of Linux distributions:

Distributions Package name Version requirements
RedHat, CentOS, Fedora openssl-devel >=1.0.1
gcc-c++ >=4.4
python-devel for Python 2.6, 2.7
python3{N}u-devel for Python 3.{N} from IUS community (python3{N}u)
python3{N}-devel for Python 3.{N} not from IUS (python3{N})
swig >=2.0
Ubuntu, Debian, LinuxMint libssl-dev >=1.0.1
g++ >=4.4
python-dev for Python 2.6, 2.7
python3-dev for Python 3.4 - 3.6
swig >=2.0
SLES, OpenSUSE openssl-devel >=1.0.1
gcc-c++ >=4.4
python-devel for Python 2.6, 2.7
python3-devel for Python 3.4 - 3.6
swig >=2.0

On some distributions, the swig package is not available in the required version. In such cases, it can be built from its sources, as follows:

  1. Install the pcre-devel package (RedHat etc. and SLES etc.) or the libpcre3 and libpcre3-dev packages (Ubuntu etc.).

  2. Download the swig source archive and unpack it:

    $ wget -q -O swig-2.0.12.tar.gz http://sourceforge.net/projects/swig/files/swig/swig-2.0.12/swig-2.0.12.tar.gz/download
$ tar -xf swig-2.0.12.tar.gz

  3. Configure and build it:

    $ cd swig-2.0.12
$ ./configure --prefix=/usr
$ make swig

  4. Install it:

    $ sudo make install

  5. Verify its version:

    $ swig -version
SWIG Version 2.0.12

Package version

The version of the pywbem package can be accessed by programs using the pywbem.__version__ variable:

pywbem._version.__version__ = '0.10.1'

Version of the pywbem package, as a string.

Possible formats for the version string are:

  • “M.N.U.dev0”: During development of future M.N.U release (not released to PyPI)
  • “M.N.U.rcX”: Release candidate X of future M.N.U release (not released to PyPI)
  • “M.N.U”: The final M.N.U release

Note: For tooling reasons, the variable is shown as pywbem._version.__version__, but it should be used as pywbem.__version__.

Supported environments

Pywbem is supported in these environments:

  • Operating Systems: Linux, Windows, OS-X
  • Python: 2.6, 2.7, 3.4, 3.5, 3.6

Limitations:

  • On Windows, pywbem is not supported on Python 2.6, because M2Crypto in the M2CryptoWin32/64 package does not support Python 2.6.
  • On Windows, pywbem has not been tested on 64-bit versions of Python, because the libxslt etc. development packages needed to install lxml that are used do not provide the link libraries in the format needed by lxml. Because lxml is only used for development and test of pywbem, just running pywbem on 64-bit versions of Windows may or may not work.

Standards conformance

Pywbem conforms to the following CIM and WBEM standards, in the version specified when following the links to the standards:

Deprecation policy

Since its v0.7.0, Pywbem attempts to be as backwards compatible as possible.

However, in an attempt to clean up some of its history, and in order to prepare for future additions, the Python namespaces visible to users of pywbem need to be cleaned up.

Also, occasionally functionality needs to be retired, because it is flawed and a better but incompatible replacement has emerged.

In pywbem, such changes are done by deprecating existing functionality, without removing it. The deprecated functionality is still supported throughout new minor releases. Eventually, a new major release will break compatibility and will remove the deprecated functionality.

In order to prepare users of pywbem for that, deprecation of functionality is stated in the API documentation, and is made visible at runtime by issuing Python warnings of type DeprecationWarning (see the Python warnings module).

Since Python 2.7, DeprecationWarning messages are suppressed by default. They can be shown for example in any of these ways:

  • By specifying the Python command line option: -W default
  • By invoking Python with the environment variable: PYTHONWARNINGS=default

It is recommended that users of the pywbem package run their test code with DeprecationWarning messages being shown, so they become aware of any use of deprecated functionality.

Here is a summary of the deprecation and compatibility policy used by pywbem, by release type:

  • New update release (M.N.U -> M.N.U+1): No new deprecations; fully backwards compatible.
  • New minor release (M.N.U -> M.N+1.0): New deprecations may be added; as backwards compatible as possible.
  • New major release (M.N.U -> M+1.0.0): Deprecated functionality may get removed; backwards compatibility may be broken.

Compatibility is always seen from the perspective of the user of pywbem, so a backwards compatible new pywbem release means that the user can safely upgrade to that new release without encountering compatibility issues.

Python namespaces

The external APIs of pywbem are defined by the symbols in the pywbem namespace. With a few exceptions, that is the only Python namespace that needs to be imported by users.

With pywbem versions prior to v0.8, it was common for users to import the sub-modules of pywbem (e.g. pywbem.cim_obj). The sub-modules that existed prior to v0.8 are still available for compatibility reasons. Starting with v0.8, the pywbem namespace was cleaned up, and not all public symbols available in the sub-module namespaces are available in the pywbem namespace anymore. The symbols in the sub-module namespaces are still available for compatibility, including those that are no longer available in the pywbem namespace. However, any use of symbols from the sub-module namespaces is deprecated starting with v0.8, and you should assume that a future version of pywbem will remove them. If you miss any symbol you were used to use, please open an issue.

New sub-modules added since pywbem v0.8 have a leading underscore in their name in order to document that they are considered an implementation detail and that they should not be imported by users.

The only exception to the single-namespace rule stated above, is the MOF compiler API, which uses the pywbem.mof_compiler namespace.

This documentation describes only the external APIs of pywbem, and omits any internal symbols and any sub-modules.

Configuration variables

Pywbem supports a very limited number of configuration variables that influence certain specific behavior.

These configuration variables are read by pywbem only after its modules have been loaded, so they can be modified by the user directly after importing pywbem. For example:

import pywbem
pywbem.ENFORCE_INTEGER_RANGE = False

Note that the pywbem source file defining these variables should not be changed by the user. Instead, the technique shown in the example above should be used to modify the configuration variables.

Note: Due to limitations of the documentatin tooling, the following configuration variables are shown in the pywbem.config namespace. However, they should be used from the pywbem namespace.

pywbem.config.ENFORCE_INTEGER_RANGE = True

Enforce the allowable value range for CIM integer types (e.g. Uint8). For details, see the CIMInt base class.

  • True (default): Pywbem enforces the allowable value range; Assigning values out of range causes ValueError to be raised.
  • False: Pywbem does not enforce the allowable value range; Assigning values out of range works in pywbem. Note that a WBEM server may or may not reject such out-of-range values.
pywbem.config.DEFAULT_ITER_MAXOBJECTCOUNT = 1000

Default setting for the MaxObjectCount attribute for all of the WBEMConnection:Iter... operations. If this attribute is not specified on a request such as IterEnumerateInstance this value will be used as the value for MaxObjectCount. Note that this does not necessarily optimize the performance of these operations.

Tutorial

This section contains a few short tutorials about using pywbem. It is intended to be enough to get people up and going who already know a bit about WBEM and CIM.

The tutorials in this section are Jupyter Notebooks, and are shown using the online Jupyter Notebook Viewer. This allows viewing the tutorials without having Jupyter Notebook installed locally.

In order to view a tutorial, just click on a link in this table:

Tutorial Short description
connections.ipynb Making connections to a WBEM server
datamodel.ipynb Representation of CIM objects in Python
enuminsts.ipynb EnumerateInstances
enuminstnames.ipynb EnumerateInstanceNames
getinstance.ipynb GetInstance
createdeleteinst.ipynb CreateInstance + DeleteInstance
modifyinstance.ipynb ModifyInstance
invokemethod.ipynb InvokeMethod
subscriptionmanager.ipynb Subscription Manager

For the following topics, tutorials are not yet available:

  • Pulled Enumerations
  • ExecQuery
  • Association Operations
  • Class Operations
  • Qualifier Operations
  • WBEMServer
  • WBEMListener
  • WBEMSubscriptionManager

Executing code in the tutorials

You cannot directly modify or execute the code in the tutorials using the Jupyter Notebook Viewer, though. In order to do that, the Jupyter Notebook Viewer provides a download button at the top right corner of the page.

You must have Jupyter Notebook installed, preferrably in a virtual Python environment, and you must have pywbem installed.

To see a list of your downloaded notebook files, start Jupyter Notebook as follows:

jupyter notebook --notebook-dir={your-notebook-dir}

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.
  • 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.
  • Exceptions - Exceptions specific to pywbem that may be raised.
  • Security considerations - Information about authentication types and certificates.

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

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

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=None)[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.

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.
  • debug (bool) –

    A boolean indicating whether logging of the last request and last reply is enabled.

    The initial value of this attribute is False. Debug logging 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.
  • operation_recorder (BaseOperationRecorder) –

    This attribute provides for recording of the operations that are executed on this connection. Initially, this attribute is None. If None, no operations are recorded. If set to an object of a subclass of BaseOperationRecorder, each operation that is executed on this connection will be recorded by invoking its record() method. All operations except the Iter... operations may be recorded. Since the Iter... operations utilize the other operations to send requests their calls are NOT recorded.

    All operations except the Iter... operations may be recorded. Since the Iter... operations utilize the other operations to send requests their calls are NOT recorded.

  • 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 implementations that implement only some of the pull operations. The method set_use_pull_operations may be used to reset all of these flags to a defined value.

    This variable is initially set from the same-named input argument. If it is None is modified when Iter...() methods are invoked, dependent on the support for pull operations in the WBEM server. After the first call , the varaible 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, 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.
__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.

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 every request 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 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 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 every request issued to the server.
    • 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 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.
    • 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 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 associators from a WBEM Server. This method frees the user of choices between the multiple AssociatorNames/AssociatorInstancePaths 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 every request issued to the server.
    • 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 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.
    • 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 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.
    • 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 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) – term: 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.
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.
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.
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.
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.

Operation recording

The WBEM client library API provides the possibility to record the WBEM operations that are executed on a connection. This is disabled by default and can be enabled by setting the operation_recorder instance variable of the WBEMConnection object to an operation recorder object, i.e. to an object of a subclass of BaseOperationRecorder.

Typical usage scenarios for operation recorders are the tracing of WBEM operations, or the generation of test cases.

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

reset()[source]

Reset all the attributes in the class

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 OpArgs_tuple(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 OpResult_tuple(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 HttpRequest_tuple(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 HttpResponse_tuple(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.
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.

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

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.

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.

__repr__()[source]

Return a string representation of the CIMInstanceName object that is suitable for debugging.

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.

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.

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.

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.

CIMClass

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

A CIM class.

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

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.

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.

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.

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, for reference properties.

    None, for non-reference properties.

  • 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, for reference properties.

    None means that the parameter is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

Security considerations

Authentication types

Authentication is the act of establishing the identity of a user on the client side to the server, and possibly also of establishing the identity of a server to the client.

There are two levels of authentication in CIM-XML:

  • TLS/SSL level authentication (only when HTTPS is used):

    This kind of authentication is also known as transport level authentication. It is used during the TLS/SSL handshake protocol, before any HTTP requests flow.

    In almost all cases (unless an anonymous cipher is used), this involves an X.509 certificate that is presented by the server (therefore called server certificate) and that allows the client to establish the identity of the server.

    It optionally involves an X.509 certificate that is presented by the client (therefore called client certificate) and that allows the server to establish the identity of the client or even of the client user, and thus can avoid the use of credentials in the HTTP level authentication.

    If a client certificate is used, the authentication scheme at the TLS/SSL level is called 2-way authentication (also known as client authentication or mutual SSL authentication). If a client certificate is not used, the authentication scheme is called 1-way authentication (also known as SSL authentication).

    Userid/password credentials do not play any role in TLS/SSL level authentication.

  • HTTP level authentication:

    This kind of authentication is used in HTTP/HTTPS requests and responses (in case of HTTPS, after the TLS/SSL handshake protocol has completed).

    In case of Basic Authentication and Digest Authentication (see RFC2617), it involves passing credentials (userid and password) via the Authenticate and WWW-Authenticate HTTP headers. In case of no authentication, credentials are not passed.

    A client can either provide the Authenticate header along with a request, hoping that the server supports the authentication scheme that was used.

    A client can also omit that header in the request, causing the server to send an error response with a WWW-Authenticate header that tells the client which authentication types are supported by the server (also known as a challenge). The client then repeats the first request with one of the supported authentication types.

    HTTP is extensible w.r.t. authentication schemes, and so is CIM-XML. However, pywbem only supports Basic Authentication and no authentication.

    X.509 certificates do not play any role in HTTP level authentication.

HTTP/HTTPS knows a third level of authentication by the use of session cookies. CIM-XML does not define how cookies would be used, and pywbem does not deal with cookies in any way (i.e. it does not pass cookies provided in a response into the next request).

The following table shows the possible combinations of protocol, TLS/SSL level and HTTP level authentication schemes, which information items need to be provided to the WBEM client 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.

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.

Use of X.509 client certificates

When using HTTPS, the TLS/SSL handshake protocol provides the option for the client to present an X.509 certificate to the server (therefore called client certificate).

This procedure is initiated by the server, by requesting that the client present a client certificate. If the client does not have one (for example, because the x509 parameter was not specified in pywbem), it must send an empty list of certificates to the server. Depending on the server configuration, the server may or may not accept an empty list. If a client certificate is presented, the server must validate it.

The server can support to accept the user identity specified in the client certificate as the user’s identity, and refrain from sending HTTP challenges that request credentials.

Authentication errors

The operation methods of WBEMConnection raise pywbem.AuthError 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

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.

WBEM server API

The WBEM server API encapsulates certain functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace of the server, or the management profiles advertised by the server.

This chapter has the following sections:

  • Example - An example on how to use the API.
  • WBEMServer - The WBEMServer class serves as a general access point for clients to WBEM servers. It allows determining the Interop namespace of the server, or the advertised management profiles.
  • ValueMapping - The ValueMapping class maps corresponding values of the Values and ValueMap qualifiers of a CIM element and supports the translation of the actual value (often an integer) to the corresponding value of the Values qualifier.

Note

The WBEM server API has been introduced in v0.9.0 as experimental and has been declared final in 0.10.0.

Example

The following example code displays some information about a WBEM server:

from pywbem import WBEMConnection, WBEMServer, ValueMapping

def explore_server(server_url, username, password):

    print("WBEM server URL:\n  %s" % server_url)

    conn = WBEMConnection(server_url, (username, password))
    server = WBEMServer(conn)

    print("Brand:\n  %s" % server.brand)
    print("Version:\n  %s" % server.version)
    print("Interop namespace:\n  %s" % server.interop_ns)

    print("All namespaces:")
    for ns in server.namespaces:
        print("  %s" % ns)

    print("Advertised management profiles:")
    org_vm = ValueMapping.for_property(server, server.interop_ns,
        'CIM_RegisteredProfile', 'RegisteredOrganization')
    for inst in server.profiles:
        org = org_vm.tovalues(inst['RegisteredOrganization'])
        name = inst['RegisteredName']
        vers = inst['RegisteredVersion']
        print("  %s %s Profile %s" % (org, name, vers))

Example output:

WBEM server URL:
  http://0.0.0.0
Brand:
  pegasus
Version:
  2.12.0
Interop namespace:
  root/PG_Interop
All namespaces:
  root/PG_InterOp
  root/PG_Internal
  root/cimv2
  root
Advertised management profiles:
  SNIA Indication Profile 1.1.0
  SNIA Indication Profile 1.2.0
  SNIA Software Profile 1.1.0
  SNIA Software Profile 1.2.0
  SNIA Profile Registration Profile 1.0.0
  SNIA SMI-S Profile 1.2.0
  SNIA Server Profile 1.1.0
  SNIA Server Profile 1.2.0
  DMTF Profile Registration Profile 1.0.0
  DMTF Indications Profile 1.1.0

WBEMServer

class pywbem.WBEMServer(conn)[source]

A representation of a WBEM server that serves as a general access point to a client.

It supports determining the Interop namespace of the server, all namespaces, its brand and version, the advertised management profiles and finally allows to retrieve the central instances of a management profile with one method invocation regardless of whether the profile implementation chose the central or scoping class profile advertisement methodology (see DSP1033).

It also provides functions to subscribe for indications.

Parameters:conn (WBEMConnection) – Connection to the WBEM server.
INTEROP_NAMESPACES = ['interop', 'root/interop', 'root/PG_Interop']

A class variable with the possible names of Interop namespaces that should be tried when determining the Interop namespace on the WBEM server.

NAMESPACE_CLASSNAMES = ['CIM_Namespace', '__Namespace']

A class variable with the possible names of CIM classes for representing CIM namespaces, that should be tried when determining the namespaces on the WBEM server.

__repr__()[source]

Return a representation of the WBEMServer object with all attributes, that is suitable for debugging.

url

The URL of the WBEM server, as a string.

conn

The connection to the WBEM server, as a WBEMConnection object.

interop_ns

The name of the Interop namespace of the WBEM server, as a string.

Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
namespace_classname

The name of the CIM class that was found to represent the CIM namespaces of the WBEM server, as a string.

Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
  • CIMError – CIM_ERR_NOT_FOUND, Namespace class could not be determined.
namespaces

A list with the names of all namespaces of the WBEM server, each list item being a string.

Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
  • CIMError – CIM_ERR_NOT_FOUND, Namespace class could not be determined.
brand

Brand of the WBEM server, as a string.

The brand string will be one of the following:

  • "OpenPegasus", for OpenPegasus
  • "SFCB", for SFCB
  • First word of the value of the ElementName property of the CIM_ObjectManager instance, for any other WBEM servers.
  • "unknown", if the ElementName property is Null.
Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
  • CIMError – CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
version

Version of the WBEM server, as a string. None, if the version cannot be determined.

Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
  • CIMError – CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
profiles

List of management profiles advertised by the WBEM server, each list item being a CIMInstance object representing a CIM_RegisteredProfile instance.

Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
get_selected_profiles(registered_org=None, registered_name=None, registered_version=None)[source]

List of management profiles advertised by the WBEM server and filtered by the input parameters for registered_org, registered_name, and registered_version parameters. Each list item is a CIMInstance object representing a CIM_RegisteredProfile instance.

Parameters:
  • profile_org (string) – the RegisteredOrganization to match the RegisteredOrganization of the profile. If None, this parameter is ignored in the filter
  • profile_name (string) – the RegisteredName. If None, this parameter is ignored in the filter
  • profile_version (string) – the RegisteredVersion. If None, this parameter is ignored in the filter
Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError – CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
  • KeyError – If an instance in the list of profiles is incomplete and does not include the required properties.
get_central_instances(profile_path, central_class=None, scoping_class=None, scoping_path=None)[source]

Determine the central instances for a management profile, and return their instance paths as a list of CIMInstanceName objects.

This method supports the following profile advertisement methodologies (see DSP1033), and attempts them in this order:

  • GetCentralInstances methodology (new in DSP1033 1.1)
  • Central class methodology
  • Scoping class methodology

Use of the scoping class methodology requires specifying the central class, scoping class and scoping path defined by the profile. If any of them is None, this method will attempt only the GetCentralInstances and central class methodologies, but not the scoping class methodology. If using these two methodologies does not result in any central instances, and the scoping class methodology cannot be used, an exception is raised.

The scoping path is a directed traversal path from the central instances to the scoping instances. Its first list item is always the association class name of the traversal hop starting at the central instances. For each further traversal hop, the list contains two more items: The class name of the near end of that hop, and the class name of the traversed association. As a result, the class names of the central instances and scoping instances are not part of the list.

Example for a 1-hop traversal:

  • central class: "CIM_Fan"
  • scoping path: ["CIM_SystemDevice"]
  • scoping class: "CIM_ComputerSystem"

Example for a 2-hop traversal:

  • central class: "CIM_Sensor"
  • scoping path: ["CIM_AssociatedSensor", "CIM_Fan",                            "CIM_SystemDevice"]
  • scoping class: "CIM_ComputerSystem"
Parameters:
  • profile_path (CIMInstanceName) – Instance path of CIM_RegisteredProfile instance representing the management profile.
  • central_class (string) –

    Class name of central class defined by the management profile.

    Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.

  • scoping_class (string) –

    Class name of scoping class defined by the management profile.

    Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.

  • scoping_path (list of string) –

    Scoping path defined by the management profile.

    Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
Returns:

List of CIMInstanceName objects representing the instance paths of the central instances of the management profile.
Raises:

ValueMapping

class pywbem.ValueMapping[source]

A utility class that translates the values of a corresponding integer-typed CIM element (property, method, parameter) that is qualified with the ValueMap and Values qualifiers, from the element value space into into its Values qualifier space.

This is done by retrieving the CIM class definition defining the CIM element in question, and by inspecting its ValueMap and Values qualifiers.

The actual translation of the values is performed by the tovalues() method.

Instances of this class should be created through one of the factory class methods: for_property(), for_method(), or for_parameter().

Value ranges ("2..4") and the indicator for unclaimed values ("..") in the ValueMap qualifier are supported.

Example: Given the following definition of a property in MOF:

[ValueMap{ "0", "2..4", "..6", "7..", "9", ".." },
 Values{ "zero", "two-four", "five-six", "seven-eight", "nine",              "unclaimed"}]
uint16 MyProp;

The following code will create a value mapping for this property and will print a few integer values and their Values strings:

vm = pywbem.ValueMapping.for_property(server, namespace, classname,                "MyProp")
for value in range(0, 12):
    print("value: %s, Values string: %r" % (value, vm.tovalues(value))

Results:
value: 0, Values string: 'zero'
value: 1, Values string: 'unclaimed'
value: 2, Values string: 'two-four'
value: 3, Values string: 'two-four'
value: 4, Values string: 'two-four'
value: 5, Values string: 'five-six'
value: 6, Values string: 'five-six'
value: 7, Values string: 'seven-eight'
value: 8, Values string: 'seven-eight'
value: 9, Values string: 'nine'
value: 10, Values string: 'unclaimed'
value: 11, Values string: 'unclaimed'
classmethod for_property(server, namespace, classname, propname)[source]

Factory method that returns a new ValueMapping instance corresponding to a CIM property.

If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).

Parameters:
  • server (WBEMServer) – The WBEM server containing the namespace.
  • namespace (string) – Name of the CIM namespace containing the class.
  • classname (string) – Name of the CIM class exposing the property. The property can be defined in that class or inherited into that class.
  • propname (string) – Name of the CIM property that defines the Values / ValueMap qualifiers.
Returns:

The new ValueMapping instance.
Raises:
classmethod for_method(server, namespace, classname, methodname)[source]

Factory method that returns a new ValueMapping instance corresponding to a CIM method.

If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).

Parameters:
  • server (WBEMServer) – The WBEM server containing the namespace.
  • namespace (string) – Name of the CIM namespace containing the class.
  • classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
  • methodname (string) – Name of the CIM method that defines the Values / ValueMap qualifiers.
Returns:

The new ValueMapping instance.
Raises:
classmethod for_parameter(server, namespace, classname, methodname, parametername)[source]

Factory method that returns a new ValueMapping instance corresponding to a CIM parameter.

If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).

Parameters:
  • server (WBEMServer) – The WBEM server containing the namespace.
  • namespace (string) – Name of the CIM namespace containing the class.
  • classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
  • methodname (string) – Name of the CIM method that has the parameter.
  • parametername (string) – Name of the CIM parameter that defines the Values / ValueMap qualifiers.
Returns:

The new ValueMapping instance.
Raises:
element

Return the corresponding CIM element of this instance, as a CIM object (CIMProperty, CIMMethod, or CIMParameter).

tovalues(element_value)[source]

Return the Values string for an element value, based on the ValueMap / Values qualifiers of the corresponding CIM element.

Parameters:

element_value (integer or CIMInt) – The value of the CIM element.
Returns:

The Values string for the element value.
Return type:

string
Raises:
  • ValueError – Element value outside of the set defined by ValueMap.
  • ValueError – No Values qualifier defined.
  • ValueError – Invalid ValueMap entry.
  • TypeError – The CIM element is not integer-typed.
  • TypeError – Element value is not an integer type.

WBEM indication API

The WBEM indication API supports subscription for and receiving of CIM indications.

This chapter has the following sections:

Note

The WBEM indication API has been introduced in v0.9.0 as experimental and has been declared final in 0.10.0.

WBEMListener

The WBEMListener class provides a thread-based WBEM listener service that can receive CIM indications from multiple WBEM servers and that calls registered callback functions to deliver the received indications.

Examples

The following example creates and runs a listener:

import sys
import logging
from socket import getfqdn
from pywbem import WBEMListener

def process_indication(indication, host):
    '''This function gets called when an indication is received.'''

    print("Received CIM indication from {host}: {ind!r}". \
        format(host=host, ind=indication))

def main():

    logging.basicConfig(stream=sys.stderr, level=logging.WARNING,
        format='%(asctime)s - %(levelname)s - %(message)s)

    certkeyfile = 'listener.pem'

    url1 = 'http://server1'
    conn1 = WBEMConnection(url1)
    server1 = WBEMServer(conn1)
    server1.determine_interop_ns()

    url2 = 'http://server2'
    conn2 = WBEMConnection(url2)
    server2 = WBEMServer(conn2)
    server2.validate_interop_ns('root/PG_InterOp')

    my_listener = WBEMListener(host=getfqdn()
                            http_port=5988,
                            https_port=5989,
                            certfile=certkeyfile,
                            keyfile=certkeyfile)
    my_listener.add_callback(process_indication)
    listener.start()

        # listener runs until executable terminated
        # or listener.stop()

See the example in section WBEMSubscriptionManager for an example of using a listener in combination with a subscription manager.

Another listener example is in the script examples/listen.py (when you clone the GitHub pywbem/pywbem project). It is an interactive Python shell that creates a listener and displays any indications it receives, in MOF format.

class pywbem.WBEMListener(host, http_port=None, https_port=None, certfile=None, keyfile=None)[source]

A WBEM listener.

The listener supports starting and stopping threads that listen for CIM-XML ExportIndication messages using HTTP and/or HTTPS, and that pass any received indications on to registered callback functions.

Parameters:
  • host (string) – IP address or host name this listener can be reached at.
  • http_port (string or integer) –

    HTTP port this listener can be reached at. Note that at least one port (HTTP or HTTPS) must be set

    None means not to set up a port for HTTP.

  • https_port (string or integer) –

    HTTPS port this listener can be reached at.

    None means not to set up a port for HTTPS.

  • certfile (string) –

    File path of certificate file to be used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.

    It is valid for the certificate file to contain a private key; the server certificate sent during SSL/TLS handshake is sent without the private key.

    None means not to use a server certificate file. Setting up a port for HTTPS requires specifying a certificate file.

  • keyfile (string) –

    File path of private key file to be used by the server during SSL/TLS handshake when creating the secure HTTPS connection.

    It is valid to specify a certificate file that contains a private key.

    None means not to use a private key file. Setting up a port for HTTPS requires specifying a private key file.
__repr__()[source]

Return a representation of the WBEMListener object with all attributes, that is suitable for debugging.

host

The IP address or host name this listener can be reached at, as a string.

http_port

The HTTP port this listener can be reached at, as an integer.

None means there is no port set up for HTTP.

https_port

The HTTPS port this listener can be reached at, as an integer.

None means there is no port set up for HTTPS.

certfile

The file path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.

None means there is no certificate file being used (that is, no port is set up for HTTPS).

keyfile

The file path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection.

None means there is no certificate file being used (that is, no port is set up for HTTPS).

logger

The logger object for this listener.

Each listener object has its own separate logger object that is created via logging.getLogger().

The name of this logger object is:

pywbem.listener.{id}

where {id} is the id() value of the listener object. Users of the listener should not look up the logger object by name, but should use this property to get to it.

By default, this logger uses the NullHandler log handler, and its log level is logging.NOTSET. This causes this logger not to emit any log messages and to propagate them to the Python root logger.

The behavior of this logger can be changed by invoking its methods (see logging.Logger). The behavior of the root logger can for example be configured using logging.basicConfig():

import sys
import logging

logging.basicConfig(stream=sys.stderr, level=logging.WARNING,
    format='%(asctime)s - %(levelname)s - %(message)s')
start()[source]

Start the WBEM listener threads, if they are not yet running.

A thread serving CIM-XML over HTTP is started if an HTTP port was specified for the listener. A thread serving CIM-XML over HTTPS is started if an HTTPS port was specified for the listener.

These server threads will handle the ExportIndication export message described in DSP0200 and they will invoke the registered callback functions for any received CIM indications.

These server threads can be stopped using the stop() method. They will be automatically stopped when the main thread terminates.

stop()[source]

Stop the WBEM listener threads, if they are running.

deliver_indication(indication, host)[source]

This function is called by the listener threads for each received indication. It is not supposed to be called by the user.

It delivers the indication to all callback functions that have been added to the listener.

If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.

Parameters:
  • indication (CIMInstance) – Representation of the CIM indication to be delivered.
  • host (string) – Host name or IP address of WBEM server sending the indication.
add_callback(callback)[source]

Add a callback function to the listener.

The callback function will be called for each indication this listener receives from any WBEM server.

If the callback function is already known to the listener, it will not be added.

Parameters:callback (callback_interface()) – Callable that is being called for each CIM indication that is received while the listener threads are running.
pywbem.callback_interface(indication, host)[source]

Interface of a callback function that is provided by the user of the API and that will be called by the listener for each received CIM indication.

Parameters:
  • indication (CIMInstance) – Representation of the CIM indication that has been received. Its path attribute is None.
  • host (string) – Host name or IP address of WBEM server sending the indication.
Raises:

Exception – If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.

WBEMSubscriptionManager

The WBEMSubscriptionManager class is a subscription manager that provides for creating and removing indication subscriptions (including indication filters and listener destinations) for multiple WBEM servers and multiple WBEM listeners and for getting information about existing indication subscriptions.

The WBEM listener is identified through its URL, so it may be a WBEMListener object or any external WBEM listener.

This subscription manager supports three types of ownership for subscription, filter and listener destination CIM instances in WBEM servers:

  • Owned

    Owned CIM instances are created via the subscription manager and their life cycle is bound to the life cycle of the registration of that WBEM server with the subscription manager via add_server().

    Owned CIM instances are deleted automatically when their WBEM server is deregistered from the subscription manager via remove_server() or remove_all_servers(). They can still explicitly be deleted by the user via the removal methods of the WBEMSubscriptionManager class.

  • Permanent

    Permanent CIM instances are created via the subscription manager and their life cycle is independent of the life cycle of the registration of that WBEM server with the subscription manager.

    Permanent CIM instances are not deleted automatically when their WBEM server is deregistered from the subscription manager. The user is responsible for their lifetime management: They can be deleted via the removal methods of the WBEMSubscriptionManager class.

  • Static

    Static CIM instances pre-exist in the WBEM server and that cannot be deleted (or created) by a WBEM client.

If a client creates a subscription between a filter and a listener destination, the types of ownership of these three CIM instances may be arbitrarily mixed, with one exception:

  • A permanent subscription cannot be created on an owned filter or an owned listener destination. Allowing that would prevent the automatic life cycle management of the owned filter or listener destination by the subscription manager. This restriction is enforced by the WBEMSubscriptionManager class.

The WBEMSubscriptionManager object remembers owned subscriptions, filters, and listener destinations. If for some reason that object gets deleted before all servers could be removed (e.g. because the Python program aborts), the corresponding CIM instances in the WBEM server still exist, but the knowledge is lost that these instances were owned by that subscription manager. Therefore, the subscription manager discovers owned subscriptions, filters, and listener destinations when a server is added. For filters, this discovery is based upon the Name property. Therefore, if the Name property is set by the user (e.g. because a management profile requires a particular name), the filter must be permanent and cannot be owned.

Examples

The following example code demonstrates the use of a subscription manager to subscribe for a CIM alert indication on a WBEM server. The WBEM listener is assumed to exist somewhere and is identified by its URL:

import sys
from socket import getfqdn
from pywbem import WBEMConnection, WBEMServer, WBEMSubscriptionManager

server_url = 'http://myserver'
server_credentials = (user, password)

listener_url = 'http://mylistener'

conn = WBEMConnection(server_url, server_credentials)
server = WBEMServer(conn)
sub_mgr = WBEMSubscriptionManager(subscription_manager_id='fred')

# Register the server in the subscription manager:
server_id = sub_mgr.add_server(server)

# Add a listener destination in the server:
dest_inst = sub_mgr.add_listener_destinations(server_id, listener_url)

# Subscribe to a static filter of a given name:
filter1_name = "DMTF:Indications:GlobalAlertIndicationFilter"
filter1_insts = sub_mgr.get_all_filters(server_id)
for inst in filter1_insts:
    if inst['Name'] == filter1_name:
        sub_mgr.add_subscriptions(server_id, inst.path, dest_inst.path)
        break

# Create a dynamic alert filter and subscribe to it:
filter2_source_ns = "root/cimv2"
filter2_query = "SELECT * FROM CIM_AlertIndication " \
                "WHERE OwningEntity = 'DMTF' " \
                "AND MessageID LIKE 'SVPC0123|SVPC0124|SVPC0125'"
filter2_language = "DMTF:CQL"
filter2_inst = subscription_manager.add_filter(server_id,
    filter2_source_ns, filter2_query, filter2_language, owned=True,
    filter_id="myalert")
sub_mgr.add_subscriptions(server_id, filter2_inst.path, dest_inst.path)

The following example code briefly shows how to use a subscription manager as a context manager, in order to get automatic cleanup of owned instances:

with WBEMSubscriptionManager('fred') as sub_mgr:
    server_id = sub_mgr.add_server(server)
    . . .
# The exit method automatically calls remove_all_servers(), which deletes
# all owned subscription, filter and destination instances in the servers
# that were registered.

The Tutorial section contains a tutorial about the subscription manager.

class pywbem.WBEMSubscriptionManager(subscription_manager_id)[source]

A class for managing subscriptions for CIM indications in a WBEM server.

The class may be used as a Python context manager, in order to get automatic clean up (see __exit__()).

Parameters:subscription_manager_id (string) –

A subscription manager ID string that is used as a component in the value of the Name property of indication filter and listener destination instances to help the user identify these instances in a WBEM server.

Must not be None.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

The subscription manager ID must be unique on the current host.

For example, the form of the Name property of a filter instance is (for details, see add_filter()):

"pywbemfilter:" {ownership} ":" {subscription_manager_id} ":" {filter_id} ":" {guid}
Raises:ValueError, TypeError for incorrect input parameters.
__repr__()[source]

Return a representation of the WBEMSubscriptionManager object with all attributes, that is suitable for debugging.

__enter__()[source]

Enter method when the class is used as a context manager. Returns the subscription manager object

__exit__(exc_type, exc_value, traceback)[source]

Exit method when the class is used as a context manager.

It cleans up by calling remove_all_servers().

add_server(server)[source]

Register a WBEM server with the subscription manager. This is a prerequisite for adding listener destinations, indication filters and indication subscriptions to the server.

This method discovers listener destination, indication filter, and subscription instances in the WBEM server that are owned by this subscription manager, and registers them in the subscription manager as if they had been created through it.

In this discovery process, listener destination and indication filter instances are matched based upon the value of their Name property. Subscription instances are matched based upon the ownership of the referenced destination and filter instances: If a subscription references a filter or a destination that is owned by this subscription manager, it is considered owned by this subscription manager as well.

Parameters:

server (WBEMServer) – The WBEM server.
Returns:

An ID for the WBEM server, for use by other methods of this class.
Return type:

string
Raises:
  • Exceptions raised by WBEMConnection.
  • ValueError, TypeError for incorrect input parameters.
remove_server(server_id)[source]

Remove a registered WBEM server from the subscription manager. This also unregisters listeners from that server and removes all owned indication subscriptions, owned indication filters and owned listener destinations that were created by this subscription manager for that server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Raises:Exceptions raised by WBEMConnection.
remove_all_servers()[source]

Remove all registered WBEM servers from the subscription manager. This also unregisters listeners from these servers and removes all owned indication subscriptions, owned indication filters, and owned listener destinations that were created by this subscription manager.

This is, in effect, a complete shutdown of the subscription manager.

Raises:Exceptions raised by WBEMConnection.
add_listener_destinations(server_id, listener_urls, owned=True)[source]

Register WBEM listeners to be the target of indications sent by a WBEM server.

This function automatically creates a listener destination instance (of CIM class “CIM_ListenerDestinationCIMXML”) for each specified listener URL in the Interop namespace of the specified WBEM server.

The form of the Name property of the created destination instance is:

"pywbemdestination:" {ownership} ":" {subscription_manager_id} ":" {guid}

where {ownership} is "owned" or "permanent" dependent on the owned argument; {subscription_manager_id} is the subscription manager ID; and {guid} is a globally unique identifier.

Owned listener destinations are added or updated conditionally: If the listener destination instance to be added is already registered with this subscription manager and has the same property values, it is not created or modified. It it has the same path but different property values, it is modified to get the desired property values. If an instance with this path does not exist yet (the normal case), it is created.

Permanent listener destinations are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.

Parameters:
  • server_id (string) – The server ID of the WBEM server, returned by add_server().
  • listener_urls (string or list of string) –

    The URL or URLs of the WBEM listeners to be registered.

    The WBEM listener may be a WBEMListener object or any external WBEM listener.

    Each listener URL string must have the format:

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

    The following URL schemes are supported:

    • https: Causes HTTPS to be used.
    • http: Causes HTTP to be used. This is the default

    The host can be specified in any of the usual formats:

    • a short or fully qualified DNS hostname
    • a literal (= dotted) IPv4 address
    • a literal IPv6 address, formatted as defined in RFC3986 with the extensions for zone identifiers as defined in RFC6874, supporting - (minus) for the delimiter before the zone ID string, as an additional choice to %25.

    Note that the port is required in listener URLs.

    See WBEMConnection for examples of valid URLs, with the caveat that the port in server URLs is optional.

  • owned (bool) – Defines the ownership type of the created listener destination instances: If True, they will be owned. Otherwise, they will be permanent. See WBEMSubscriptionManager for details about these ownership types.
Returns:

The created listener destination instances for the defined listener URLs.
Return type:

list of CIMInstance
Raises:

Exceptions raised by WBEMConnection.
get_owned_destinations(server_id)[source]

Return the owned listener destinations in a WBEM server that have been created by this subscription manager.

This function accesses only the local list of owned destinations; it does not contact the WBEM server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:The listener destination instances.
Return type:list of CIMInstance
get_all_destinations(server_id)[source]

Return all listener destinations in a WBEM server.

This function contacts the WBEM server and retrieves the listener destinations by enumerating the instances of CIM class “CIM_ListenerDestinationCIMXML” in the Interop namespace of the WBEM server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:The listener destination instances.
Return type:list of CIMInstance
Raises:Exceptions raised by WBEMConnection.
remove_destinations(server_id, destination_paths)[source]

Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.

The listener destinations must be owned or permanent (i.e. not static).

This method verifies that there are not currently any subscriptions on the listener destinations to be removed, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.

Parameters:
Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError(CIM_ERR_FAILED) if there are referencing subscriptions.
add_filter(server_id, source_namespace, query, query_language='WQL', owned=True, filter_id=None, name=None)[source]

Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class “CIM_IndicationFilter”) in the Interop namespace of the server.

The Name property of the created filter instance can be set in one of two ways:

  • directly by specifying the name parameter.

    In this case, the Name property is set directly to the name parameter.

    This should be used in cases where the user needs to have control over the filter name (e.g. because a DMTF management profile requires a particular name), but it cannot be used for owned filters.

  • indirectly by specifying the filter_id parameter.

    In this case, the value of the Name property will be:

    "pywbemfilter:" {ownership} ":" {subscription_manager_id} ":" {filter_id} ":" {guid}

    where {ownership} is "owned" or "permanent" dependent on whether the filter is owned or permmanent; {subscription_manager_id} is the subscription manager ID; {filter_id} is the filter ID; and {guid} is a globally unique identifier.

    This can be used for both owned and permanent filters.

Owned indication filters are added or updated conditionally: If the indication filter instance to be added is already registered with this subscription manager and has the same property values, it is not created or modified. It it has the same path but different property values, it is modified to get the desired property values. If an instance with this path does not exist yet (the normal case), it is created.

Permanent indication filters are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.

Parameters:
  • server_id (string) – The server ID of the WBEM server, returned by add_server().
  • source_namespace (string) – Source namespace of the indication filter.
  • query (string) – Filter query in the specified query language.
  • query_language (string) –

    Query language for the specified filter query.

    Examples: ‘WQL’, ‘DMTF:CQL’.

  • owned (bool) – Defines the ownership type of the created indication filter instance: If True, it will be owned. Otherwise, it will be permanent. See WBEMSubscriptionManager for details about these ownership types.
  • filter_id (string) –

    A filter ID string that is used as a component in the value of the Name property of filter instances to help the user identify these instances in a WBEM server, or None if the name parameter is specified.

    The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

    There is no requirement that the filter ID be unique. This can be used to identify groups of filters by using the same value for multiple filters.

  • name (string) – The filter name to be used directly for the Name property of the filter instance, or None if the filter_id parameter is specified.
Returns:

The created indication filter instance.
Return type:

CIMInstance
Raises:
  • Exceptions raised by WBEMConnection.
  • ValueError, TypeError for incorrect input parameters.
get_owned_filters(server_id)[source]

Return the owned indication filters in a WBEM server that have been created by this subscription manager.

This function accesses only the local list of owned filters; it does not contact the WBEM server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:The indication filter instances.
Return type:list of CIMInstance
get_all_filters(server_id)[source]

Return all indication filters in a WBEM server.

This function contacts the WBEM server and retrieves the indication filters by enumerating the instances of CIM class “CIM_IndicationFilter” in the Interop namespace of the WBEM server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:The indication filter instances.
Return type:list of CIMInstance
Raises:Exceptions raised by WBEMConnection.
remove_filter(server_id, filter_path)[source]

Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server.

The indication filter must be owned or permanent (i.e. not static).

This method verifies that there are not currently any subscriptions on the specified indication filter, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.

Parameters:
  • server_id (string) – The server ID of the WBEM server, returned by add_server().
  • filter_path (CIMInstanceName) – Instance path of the indication filter instance in the WBEM server.
Raises:
  • Exceptions raised by WBEMConnection.
  • CIMError(CIM_ERR_FAILED) if there are referencing subscriptions.
add_subscriptions(server_id, filter_path, destination_paths=None, owned=True)[source]

Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destinations, by creating indication subscription instances (of CIM class “CIM_IndicationSubscription”) in the Interop namespace of that server.

The specified indication filter may be owned, permanent or static.

The specified listener destinations may be owned, permanent or static.

When creating permanent subscriptions, the indication filter and the listener destinations must not be owned.

Owned subscriptions are added or updated conditionally: If the subscription instance to be added is already registered with this subscription manager and has the same property values, it is not created or modified. It it has the same path but different property values, it is modified to get the desired property values. If an instance with this path does not exist yet (the normal case), it is created.

Permanent subscriptions are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.

Upon successful return of this method, the added subscriptions are active, so that the specified WBEM listeners may immediately receive indications.

Parameters:
  • server_id (string) – The server ID of the WBEM server, returned by add_server().
  • filter_path (CIMInstanceName) – Instance path of the indication filter instance in the WBEM server that specifies the indications to be sent.
  • destination_paths (CIMInstanceName or list of CIMInstanceName) –

    Instance paths of the listener destination instances in the WBEM server that specify the target WBEM listener.

    If None, subscriptions will be created for all owned listener destinations registered to this subscription manager.

  • owned (bool) – Defines the ownership type of the created subscription instances: If True, they will be owned. Otherwise, they will be permanent. See WBEMSubscriptionManager for details about these ownership types.
Returns:

The indication subscription instances created in the WBEM server.
Return type:

list of CIMInstance
Raises:
  • Exceptions raised by WBEMConnection.
  • ValueError for incorrect input parameters.
get_owned_subscriptions(server_id)[source]

Return the owned indication subscriptions for a WBEM server that have been created by this subscription manager.

This function accesses only the local list of owned subscriptions; it does not contact the WBEM server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:The indication subscription instances.
Return type:list of CIMInstance
get_all_subscriptions(server_id)[source]

Return all indication subscriptions in a WBEM server.

This function contacts the WBEM server and retrieves the indication subscriptions by enumerating the instances of CIM class “CIM_IndicationSubscription” in the Interop namespace of the WBEM server.

Parameters:server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:The indication subscription instances.
Return type:list of CIMInstance
Raises:Exceptions raised by WBEMConnection.
remove_subscriptions(server_id, sub_paths)[source]

Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.

The indication subscriptions must be owned or permanent (i.e. not static).

Parameters:
Raises:

Exceptions raised by WBEMConnection.

MOF compiler API

The language in which CIM classes are specified, is called MOF (for Managed Object Format). It is defined in DSP0004.

The pywbem package includes a MOF compiler.

MOF compilers take MOF files as input, compile them and the result is used to update a target CIM repository. The repository may initially be empty, or may contain the result of earlier MOF compilations that are used to resolve dependencies the new MOF compilation may have.

The MOF compiler in this package also has an option to remove CIM elements from the repository it has a definition for in the MOF files it processes.

The MOF compiler API provides for invoking the MOF compiler and for plugging in your own CIM repository into the MOF compiler.

The MOF compiler API is available in the pywbem.mof_compiler module.

This chapter has the following sections:

MOFCompiler

class pywbem.mof_compiler.MOFCompiler(handle, search_paths=None, verbose=False, log_func=<function _print_logger>)[source]

A MOF compiler.

A MOF compiler is associated with a CIM repository. The repository is used for looking up dependent CIM elements (e.g. the superclass specified in a class whose MOF definition is being compiled), and it is also updated with the result of the compilation. A repository contains CIM namespaces, and the namespaces contain CIM classes, instances and qualifier types.

The association with a CIM repository is established when creating an instance of this class. The interactions with the CIM repository are defined in the abstract base class BaseRepositoryConnection.

Parameters:
  • handle (BaseRepositoryConnection) –

    A connection to the CIM repository that will be associated with the MOF compiler.

    None means that no CIM repository will be associated. In this case, the MOF compiler can only process standalone MOF that does not depend on existing CIM elements in the repository.

  • search_paths (iterable of string) – An iterable of path names of directories where MOF include files should be looked up.
  • verbose (bool) – Indicates whether to issue more detailed compiler messages.
  • log_func (callable) – A logger function that is invoked for each compiler message. The logger function must take one parameter of string type. The default logger prints to stdout.
compile_string(mof, ns, filename=None)[source]

Compile a string of MOF statements into a namespace of the associated CIM repository.

Parameters:
  • mof (string) – The string of MOF statements to be compiled.
  • ns (string) – The name of the CIM namespace in the associated CIM repository that is used for lookup of any dependent CIM elements, and that is also the target of the compilation.
  • filename (string) – The path name of the file that the MOF statements were read from. This information is used only in compiler messages.
Raises:
  • MOFParseError – Syntax error in the MOF.
  • Any exceptions that are raised by the repository connection class.
compile_file(filename, ns)[source]

Compile a MOF file into a namespace of the associated CIM repository.

Parameters:
  • filename (string) – The path name of the MOF file containing the MOF statements to be compiled.
  • ns (string) – The name of the CIM namespace in the associated CIM repository that is used for lookup of any dependent CIM elements, and that is also the target of the compilation.
Raises:
  • MOFParseError – Syntax error in the MOF.
  • Any exceptions that are raised by the repository connection class.
find_mof(classname)[source]

Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler.

The MOF file is found based on its file name: It is assumed that the base part of the file name is the CIM class name.

Example: The class “CIM_ComputerSystem” is expected to be in a file “CIM_ComputerSystem.mof”.

Parameters:classame (string) – The name of the CIM class to look up.
Returns:A string with the path name of the MOF file, if it was found. None, otherwise.
rollback(verbose=False)[source]

Rollback any changes to the CIM repository that were performed by compilations using this MOF compiler object, since the object was created.

Repository connections

class pywbem.mof_compiler.BaseRepositoryConnection[source]

An abstract base class for implementing repository connections for the MOF compiler. This class defines the interface that is used by the MOF compiler (class MOFCompiler) when it interacts with the repository.

Class MOFCompiler invokes only the operations that are defined as methods on this class. Specifically, it does not invoke:

  • EnumerateInstances
  • GetInstance
  • EnumerateClasses
  • EnumerateClassNames
  • association or query operations
  • method invocations

Exceptions:

Implementation classes should raise only exceptions derived from Error. Other exceptions are considered programming errors.
default_namespace

The default repository namespace, as a string (readable and writeable).

EnumerateInstanceNames(*args, **kwargs)[source]

Enumerate instance paths of CIM instances in the repository.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateInstanceNames().

CreateInstance(*args, **kwargs)[source]

Create a CIM instance in the repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateInstance().

ModifyInstance(*args, **kwargs)[source]

Modify a CIM instance in the repository.

For a description of the parameters, see pywbem.WBEMConnection.ModifyInstance().

DeleteInstance(*args, **kwargs)[source]

Delete a CIM instance in the repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteInstance().

GetClass(*args, **kwargs)[source]

Retrieve a CIM class from the repository.

For a description of the parameters, see pywbem.WBEMConnection.GetClass().

ModifyClass(*args, **kwargs)[source]

Modify a CIM class in the repository.

For a description of the parameters, see pywbem.WBEMConnection.ModifyClass().

CreateClass(*args, **kwargs)[source]

Create a CIM class in the repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateClass().

DeleteClass(*args, **kwargs)[source]

Delete a CIM class in the repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteClass().

EnumerateQualifiers(*args, **kwargs)[source]

Enumerate the qualifier types in the repository.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateQualifiers().

GetQualifier(*args, **kwargs)[source]

Retrieve a qualifier type from the repository.

For a description of the parameters, see pywbem.WBEMConnection.GetQualifier().

SetQualifier(*args, **kwargs)[source]

Create or modify a qualifier type in the repository.

For a description of the parameters, see pywbem.WBEMConnection.SetQualifier().

DeleteQualifier(*args, **kwargs)[source]

Delete a qualifier type from the repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteQualifier().

class pywbem.mof_compiler.MOFWBEMConnection(conn=None)[source]

A repository connection that stores CIM elements locally in the instance of this class. It also supports removal of CIM elements via its rollback() method, by rolling back the changes applied locally to the instance.

It is instantiated on top of an underlying repository connection that is connected with the CIM repository that is actually being updated.

This class implements the BaseRepositoryConnection interface.

Exceptions:

The methods of this class may raise any exceptions described for class WBEMConnection.
Parameters:conn (BaseRepositoryConnection) –

The underlying repository connection.

None means that there is no underlying repository and all operations performed through this object will fail.
getns()

Return either connection default or universal default namespace

setns(value)

Set the namespace in value into either the connection default or package wide default namespace

default_namespace

The default repository namespace, as a string (readable and writeable).

EnumerateInstanceNames(*args, **kwargs)[source]

This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND. Because the operations of this class silently create every namespace that is needed and never return that error, this method is never called, and is therefore not implemented.

ModifyInstance(*args, **kwargs)[source]

This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance. Because CreateInstance() overwrites existing instances, this method is never called, and is therefore not implemented.

CreateInstance(*args, **kwargs)[source]

Create a CIM instance in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.CreateInstance().

DeleteInstance(*args, **kwargs)[source]

This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

GetClass(*args, **kwargs)[source]

Retrieve a CIM class from the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.GetClass().

ModifyClass(*args, **kwargs)[source]

This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class. Because CreateClass() overwrites existing classes, this method is never called, and is therefore not implemented.

CreateClass(*args, **kwargs)[source]

Create a CIM class in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.CreateClass().

DeleteClass(*args, **kwargs)[source]

This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

EnumerateQualifiers(*args, **kwargs)[source]

Enumerate the qualifier types in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateQualifiers().

GetQualifier(*args, **kwargs)[source]

Retrieve a qualifier type from the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.GetQualifier().

SetQualifier(*args, **kwargs)[source]

Create or modify a qualifier type in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.SetQualifier().

DeleteQualifier(*args, **kwargs)[source]

This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

rollback(verbose=False)[source]

Remove classes and instances from the underlying repository, that have been created in the local repository of this class.

Limitation: At this point, only classes and instances will be removed, but not qualifiers.

Exceptions

class pywbem.mof_compiler.MOFParseError(parser_token=None, msg=None)[source]

Exception raised when MOF cannot be parsed correctly, e.g. for syntax errors. Derived from Error.

Parameters:
  • parser_token – PLY parser token for the error (that is, the p argument of a PLY parser function). This token contains information on the location of the error in the MOF file, which is copied into this object, and is accessible via properties.
  • msg (string) – Message text supplied by the creator of the error
lineno

Line number in the MOF file where the error occurred.

column

Position within the line where the error occurred.

file

File name of the MOF file where the error occurred, as a string.

context

Context string that can be inserted when printing the error message. The context string consists of a first line with a segment of the MOF surrounding the error position, and a second line that uses the ‘^’ character to indicate the token in error.

msg

Message that may be part of the error, as a string. Generally, this is produced when the actual error position is not known but may be added by some production errors.

get_err_msg()[source]

Return the MOF compiler error message as a string, in the format (assuming all components are provided):

Syntax error:<file>:<lineno>: <msg>
<context - MOF segment>
<context - location indicator>

WBEM utility commands

The pywbem package provides a number of WBEM utility commands. They are all implemented as pure-Python scripts.

These commands are installed into the Python script directory and should therefore automatically be available in the command search path.

The following commands are provided:

  • mof_compiler

    A MOF compiler that takes MOF files as input and creates, updates or removes CIM instances, classes or qualifier types in a CIM repository.

  • wbemcli

    A WBEM command line interface that provides an interactive Python environment for issuing WBEM operations to a WBEM server.

mof_compiler

The mof_compiler command is a MOF compiler. It compiles MOF files, and updates the repository of a WBEM server with the result.

The MOF compiler can also be invoked from programs via the MOF compiler API.

The MOF compiler has a pluggable interface for the CIM repository. The default implementation of that interface uses a WBEM server as its repository. The plug interface is also described in the MOF compiler API.

Usage

Here is the help text of the command:

usage: mof_compiler [options] moffile ...

Compile MOF files, and update a namespace in a WBEM server with the result.

Positional arguments:
  moffile               Path name of the MOF file to be compiled.
                        Can be specified multiple times.

Server related options:
  Specify the WBEM server and namespace the MOF compiler works against, for
  looking up existing elements, and for applying the MOF compilation results
  to.

  -s url, --server url  Host name or URL of the WBEM server (required),
                        in this format:
                            [scheme://]host[:port]
                        - scheme: Defines the protocol to use:
                            - "https" for HTTPS protocol
                            - "http" for HTTP protocol
                          Default: "https".
                        - host: Defines host name as follows:
                             - short or fully qualified DNS hostname
                             - literal IPV4 address(dotted)
                             - literal IPV6 address (RFC 3986) with zone
                               identifier extensions(RFC 6874)
                               supporting "-" or %25 for the delimiter
                        - port: Defines the WBEM server port to be used.
                          Defaults:
                             - 5988, when using HTTP
                             - 5989, whenusing HTTPS
  -n namespace, --namespace namespace
                        Namespace in the WBEM server.
                        Default: root/cimv2

Connection security related options:
  Specify user name and password or certificates and keys

  -u user, --user user  User name for authenticating with the WBEM server.
                        Default: No user name.
  -p password, --password password
                        Password for authenticating with the WBEM server.
                        Default: Will be prompted for, if user name
                        specified.
  -nvc, --no-verify-cert
                        Client will not verify certificate returned by the
                        WBEM server (see cacerts). This bypasses the client-
                        side verification of the server identity, but allows
                        encrypted communication with a server for which the
                        client does not have certificates.
  --cacerts cacerts     File or directory containing certificates that will be
                        matched against a certificate received from the WBEM
                        server. Set the --no-verify-cert option to bypass
                        client verification of the WBEM server certificate.
                        Default: Searches for matching certificates in the
                        following system directories:
                        /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
                        /etc/ssl/certs
                        /etc/ssl/certificates
  --certfile certfile   Client certificate file for authenticating with the
                        WBEM server. If option specified the client attempts
                        to execute mutual authentication.
                        Default: Simple authentication.
  --keyfile keyfile     Client private key file for authenticating with the
                        WBEM server. Not required if private key is part of the
                        certfile option. Not allowed if no certfile option.
                        Default: No client key file. Client private key should
                        then be part  of the certfile

Action related options:
  Specify actions against the WBEM server's namespace. Default:
  Create/update elements.

  -r, --remove          Remove elements (found in the MOF files) from the WBEM
                        server's namespace, instead of creating or updating
                        them
  -d, --dry-run         Don't actually modify the WBEM server's namespace,
                        just check MOF syntax. Connection to WBEM server is
                        still required to check qualifiers.

General options:
  -I dir, --include dir
                        Path name of a MOF include directory. Can be specified
                        multiple times.
  -v, --verbose         Print more messages while processing
  -h, --help            Show this help message and exit

Example: mof_compiler CIM_Schema_2.45.mof -s https://localhost -n root/cimv2
-u sheldon -p p42

wbemcli

The wbemcli command is a WBEM client command line interface (CLI). It is implemented as an interactive shell.

The WBEM client CLI does not have an external API on its own; it is for the most part a consumer of the WBEM client library API.

Usage

Here is the help text of the command:

usage: wbemcli [options] server

Provide an interactive shell for issuing operations against a WBEM server.

wbemcli executes the WBEMConnection as part of initialization so the user can
input requests as soon as the interactive shell is started.

Use h() in thenteractive shell for help for wbemcli methods and variables.

Positional arguments:
  server                Host name or url of the WBEM server in this format:
                            [{scheme}://]{host}[:{port}]
                        - scheme: Defines the protocol to use;
                            - "https" for HTTPs protocol
                            - "http" for HTTP protocol.
                          Default: "https".
                        - host: Defines host name as follows:
                             - short or fully qualified DNS hostname,
                             - literal IPV4 address(dotted)
                             - literal IPV6 address (RFC 3986) with zone
                               identifier extensions(RFC 6874)
                               supporting "-" or %25 for the delimiter.
                        - port: Defines the WBEM server port to be used
                          Defaults:
                             - HTTP  - 5988
                             - HTTPS - 5989

Server related options:
  Specify the WBEM server namespace and timeout

  -n namespace, --namespace namespace
                        Default namespace in the WBEM server for operation
                        requests when namespace option not supplied with
                        operation request.
                        Default: root/cimv2
  -t timeout, --timeout timeout
                        Timeout of the completion of WBEM Server operation
                        in seconds(integer between 0 and 300).
                        Default: No timeout

Connection security related options:
  Specify user name and password or certificates and keys

  -u user, --user user  User name for authenticating with the WBEM server.
                        Default: No user name.
  -p password, --password password
                        Password for authenticating with the WBEM server.
                        Default: Will be prompted for, if user name
                        specified.
  -nvc, --no-verify-cert
                        Client will not verify certificate returned by the
                        WBEM server (see cacerts). This bypasses the client-
                        side verification of the server identity, but allows
                        encrypted communication with a server for which the
                        client does not have certificates.
  --cacerts cacerts     File or directory containing certificates that will be
                        matched against a certificate received from the WBEM
                        server. Set the --no-verify-cert option to bypass
                        client verification of the WBEM server certificate.
                        Default: Searches for matching certificates in the
                        following system directories:
                        /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
                        /etc/ssl/certs
                        /etc/ssl/certificates
  --certfile certfile   Client certificate file for authenticating with the
                        WBEM server. If option specified the client attempts
                        to execute mutual authentication.
                        Default: Simple authentication.
  --keyfile keyfile     Client private key file for authenticating with the
                        WBEM server. Not required if private key is part of the
                        certfile option. Not allowed if no certfile option.
                        Default: No client key file. Client private key should
                        then be part  of the certfile

General options:
  -s [scripts [scripts ...]], --scripts [scripts [scripts ...]]
                        Execute the python code defined by the script before the
                        user gets control. This argument may be repeated to load
                        multiple scripts or multiple scripts may be listed for a
                        single use of the option. Scripts are executed after the
                        WBEMConnection call
  -v, --verbose         Print more messages while processing
  -h, --help            Show this help message and exit

Examples:
  wbemcli https://localhost:15345 -n vendor -u sheldon -p penny
          - (https localhost, port=15345, namespace=vendor user=sheldon
         password=penny)

  wbemcli http://[2001:db8::1234-eth0] -(http port 5988 ipv6, zone id eth0)

Global functions

The interactive shell of wbemcli provides global functions for the CIM operations, and some functions for help display and debugging.

For tooling reasons, these functions are shown as members of the ‘wbemcli’ namespace. However, they are directly available in the namespace of the wbemcli interactive shell.

wbemcli.ein(cn, ns=None)[source]

WBEM operation: EnumerateInstanceNames

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

Parameters:
  • cn (string or CIMClassName) –

    Name of the class to be enumerated (case independent).

    If specified as a CIMClassName object, its host attribute will be ignored.

  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
Returns:

The 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: None, indicating the WBEM server is unspecified.
Return type:

list of CIMInstanceName
wbemcli.ei(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None)[source]

WBEM operation: EnumerateInstances

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

Parameters:
  • cn (string or CIMClassName) –

    Name of the class to be enumerated (case independent).

    If specified as a CIMClassName object, its host attribute will be ignored.

  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.

  • lo (bool) –

    LocalOnly flag: Exclude inherited properties.

    If None, this parameter will not be sent to the server, and the server default of True will be used.

    Deprecated: Server implementations for True vary; therefore it is recommended to set this parameter to False.

  • di (bool) –

    DeepInheritance flag: Include properties added by subclasses.

    If None, this parameter will not be sent to the server, and the server default of True will be used.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    If None, this parameter will not be sent to the server, and the server default of True will be used.

    Deprecated: Instance qualifiers have been deprecated in CIM. Clients cannot rely on qualifiers to be returned in this operation.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for properties.

    If None, this parameter will not be sent to the server, and the server default of False will be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns:

The instances, with their path attribute being 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.
Return type:

list of CIMInstance
wbemcli.gi(ip, lo=None, iq=None, ico=None, pl=None)[source]

WBEM operation: GetInstance

Retrieve an instance.

Parameters:
  • ip (CIMInstanceName) –

    Instance path.

    If this object does not specify a namespace, the default namespace of the connection is used.

    Its host attribute will be ignored.

  • lo (bool) –

    LocalOnly flag: Exclude inherited properties.

    If None, this parameter will not be sent to the server, and the server default of True will be used.

    Deprecated: Server implementations for True vary; therefore it is recommended to set this parameter to False.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    If None, this parameter will not be sent to the server, and the server default of False will be used.

    Deprecated: Instance qualifiers have been deprecated in CIM. Clients cannot rely on qualifiers to be returned in this operation.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for properties.

    If None, this parameter will not be sent to the server, and the server default of False will be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns:

The instance, with its path attribute being 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.
Return type:

CIMInstance
wbemcli.mi(mi, iq=None, pl=None)[source]

WBEM operation: ModifyInstance

Modify the property values of an instance.

Parameters:
  • mi (CIMInstance) –

    Modified instance, also indicating its instance path.

    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.

  • iq (bool) –

    IncludeQualifiers flag: Modify instance qualifiers as specified in the instance.

    If None, this parameter will not be sent to the server, and the server default of False will be used.

    Deprecated: Instance qualifiers have been deprecated in CIM. Clients cannot rely on qualifiers to be modified in this operation.

  • pl (iterable of string) – PropertyList: Names of properties to be modified (if not otherwise excluded). If None, all properties will be modified.
wbemcli.ci(ni, ns=None)[source]

WBEM operation: CreateInstance

Create an instance in a namespace.

Parameters:
  • ni (CIMInstance) –

    New instance.

    Its classname attribute specifies the creation class. Its properties attribute specifies initial property values. Its path attribute is ignored, except for providing a default namespace.

  • ns (string) –

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

    If None, defaults to the namespace in the path attribute of the ni parameter, or to the default namespace of the connection.
Returns:

The instance path, 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.
Return type:

CIMInstanceName
wbemcli.di(ip)[source]

WBEM operation: DeleteInstance

Delete an instance.

Parameters:ip (CIMInstanceName) –

Instance path.

If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
wbemcli.an(op, ac=None, rc=None, r=None, rr=None)[source]

WBEM operation: AssociatorNames

Instance level use: Retrieve the instance paths of the instances associated to a source instance.

Class level use: Retrieve the class paths of the classes associated to a source class.

Parameters:
  • op (CIMClassName) – Source instance path; select instance level use.
  • op – Source class path; select class level use.
  • ac (string) –

    AssociationClass filter: Include only traversals across this association class.

    None means this filter is not applied.

  • rc (string) –

    ResultClass filter: Include only traversals to this associated (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • rr (string) –

    ResultRole filter: Include only traversals to this role (= reference name) in associated (=result) objects.

    None means this filter is not applied.
Returns:

For instance level use, a list of CIMInstanceName objects representing the 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, or None if the server did not return host information.

For class level use, a list of CIMClassName objects representing the class paths, 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.
Return type:

list of CIMInstanceName or CIMClassName
wbemcli.a(op, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None)[source]

WBEM operation: Associators

Instance level use: Retrieve the instances associated to a source instance.

Class level use: Retrieve the classes associated to a source class.

Parameters:
  • op (CIMClassName) – Source instance path; select instance level use.
  • op – Source class path; select class level use.
  • ac (string) –

    AssociationClass filter: Include only traversals across this assoiation class.

    None means this filter is not applied.

  • rc (string) –

    ResultClass filter: Include only traversals to this associated (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • rr (string) –

    ResultRole filter: Include only traversals to this role (= reference name) in associated (=result) objects.

    None means this filter is not applied.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    Deprecated: Instance qualifiers have been deprecated in CIM.

    None will cause the server default of False to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    Deprecated: Server impls. vary; Server may treat as False.

    None will cause the server default of False to be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns:

For instance level use, a list of CIMInstance objects representing the instances, with their path attribute being 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 use, a list of tuple (classpath, class) representing the classes, with the following (unnamed) tuple items:

  • classpath (CIMClassName): Class path 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.
Return type:

list of CIMInstance or tuple (CIMClassName, CIMClass)
wbemcli.rn(op, rc=None, r=None)[source]

WBEM operation: ReferenceNames

Instance level use: Retrieve the instance paths of the association instances referencing a source instance.

Class level use: Retrieve the class paths of the association classes referencing a source class.

Parameters:
  • op (CIMClassName) – Source instance path; select instance level use.
  • op – Source class path; select class level use.
  • rc (string) –

    ResultClass filter: Include only traversals across this association (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.
Returns:

For instance level use, a list of CIMInstanceName objects representing the 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, or None if the server did not return host information.

For class level use, a list of CIMClassName objects representing the class paths, 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.
Return type:

list of CIMInstanceName or CIMClassName
wbemcli.r(op, rc=None, r=None, iq=None, ico=None, pl=None)[source]

WBEM operation: References

Instance level use: Retrieve the association instances referencing a source instance.

Class level use: Retrieve the association classes referencing a source class.

Parameters:
  • op (CIMClassName) – Source instance path; select instance level use.
  • op – Source class path; select class level use.
  • rc (string) –

    ResultClass filter: Include only traversals across this association (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    Deprecated: Instance qualifiers have been deprecated in CIM.

    None will cause the server default of False to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    Deprecated: Server impls. vary; Server may treat as False.

    None will cause the server default of False to be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns:

For instance level use, a list of CIMInstance objects representing the instances, with their path attribute being 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 use, a list of tuple (classpath, class) representing the classes, with the following (unnamed) tuple items:

  • classpath (CIMClassName): Class path 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.
Return type:

list of CIMInstance or tuple (CIMClassName, CIMClass)
wbemcli.oei(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenEnumerateInstances

Open an enumeration sequence to enumerate the instances of a class (including instances of its subclasses) in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • cn (string or CIMClassName) –

    Name of the class to be enumerated (case independent).

    If specified as a CIMClassName object, its host attribute will be ignored.

  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.

  • lo (bool) –

    LocalOnly flag: Exclude inherited properties.

    Deprecated: Server impls for True vary; Set to False.

    None will cause the server default of True to be used.

  • di (bool) –

    DeepInheritance flag: Include properties added by subclasses.

    None will cause the server default of True to be used.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    Deprecated: Instance qualifiers have been deprecated in CIM.

    None will cause the server default of False to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    Deprecated: Server may treat as False.

    None will cause the server default of False to be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
  • fl (string) –

    Filter query language to be used for the filter defined in the fi parameter.

    None means that no such filtering is peformed.

  • fq (string) –

    Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.

    None means that no such filtering is peformed.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

instances (list of CIMInstance):

The result set of instances in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.oeip(cn, ns=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenEnumerateInstancePaths

Open an enumeration sequence to enumerate the instances of a class (including instances of its subclasses) in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • cn (string or CIMClassName) –

    Name of the class to be enumerated (case independent).

    If specified as a CIMClassName object, its host attribute will be ignored.

  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.

  • lo (bool) –

    LocalOnly flag: Exclude inherited properties.

    Deprecated: Server impls for True vary; Set to False.

    None will cause the server default of True to be used.

  • fl (string) –

    Filter query language to be used for the filter defined in the fi parameter.

    None means that no such filtering is peformed.

  • fq (string) –

    Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.

    None means that no such filtering is peformed.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

paths (list of CIMInstanceName):

The result set of instance paths in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.ori(op, rc=None, r=None, iq=None, ico=None, pl=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenReferenceInstances

Open an enumeration sequence to enumerate the association instances of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • op (CIMInstanceName) – Source instance path.
  • rc (string) –

    ResultClass filter: Include only traversals across this association (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    Deprecated: Instance qualifiers have been deprecated in CIM.

    None will cause the server default of False to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    Deprecated: Server impls. vary; Server may treat as False.

    None will cause the server default of False to be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
  • fl (string) –

    Filter query language to be used for the filter defined in the fi parameter.

    None means that no such filtering is peformed.

  • fq (string) –

    Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.

    None means that no such filtering is peformed.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

instances (list of CIMInstance):

The result set of instances in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.orip(op, rc=None, r=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenReferenceInstancePaths

Open an enumeration sequence to enumerate the association instance paths of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • op (CIMInstanceName) – Source instance path.
  • rc (string) –

    ResultClass filter: Include only traversals across this association (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • fl (string) –

    Filter query language to be used for the filter defined in the fi parameter.

    None means that no such filtering is peformed.

  • fq (string) –

    Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.

    None means that no such filtering is peformed.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

paths (list of CIMInstanceName):

The result set of instance paths in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.oai(op, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenAssociatorInstances

Open an enumeration sequence to enumerate the associated instances of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • op (CIMInstanceName) – Source instance path.
  • ac (string) –

    AssociationClass filter: Include only traversals across this association class.

    None means this filter is not applied.

  • rc (string) –

    ResultClass filter: Include only traversals to this associated (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • rr (string) –

    ResultRole filter: Include only traversals to this role (= reference name) in associated (=result) objects.

    None means this filter is not applied.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    Deprecated: Instance qualifiers have been deprecated in CIM.

    None will cause the server default of False to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    Deprecated: Server impls. vary; Server may treat as False.

    None will cause the server default of False to be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
  • fl (string) –

    Filter query language to be used for the filter defined in the fi parameter.

    None means that no such filtering is peformed.

  • fq (string) –

    Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.

    None means that no such filtering is peformed.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

instances (list of CIMInstance):

The result set of instances in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.oaip(op, ac=None, rc=None, r=None, rr=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenAssociatorInstancePaths

Open an enumeration sequence to enumerate the associated instance paths of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • op (CIMInstanceName) – Source instance path.
  • rc (string) –

    ResultClass filter: Include only traversals across this association (result) class.

    None means this filter is not applied.

  • r (string) –

    Role filter: Include only traversals from this role (= reference name) in source object.

    None means this filter is not applied.

  • fl (string) –

    Filter query language to be used for the filter defined in the fi parameter.

    None means that no such filtering is peformed.

  • fq (string) –

    Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.

    None means that no such filtering is peformed.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

paths (list of CIMInstanceName):

The result set of instance paths in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.oqi(ql, qi, ns=None, rc=None, ot=None, coe=None, moc=None)[source]

WBEM operation: OpenQueryInstances

Open an enumeration sequence to execute a query fi using the query language fl. If this operation returns eos == False, the PullInstances operation is used to request additional instances.

This operation returns a named tuple containing any instances returned and status of the enumeration sequence.

Parameters:
  • ql (string) – Filter query language to be used for the filter defined in the qi parameter. This must be a query language such as CQL or WQL but NOT FQL.
  • qi (string) – Filter to apply to objects to be returned. Based on filter query language defined by the ql parameter.
  • ns (string) –

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

    If None, defaults to the default namespace of the connection.

  • rc (bool) –

    Controls whether a result class definition describing the returned instances will be returned.

    None will cause the server to use its default of False.

  • ot (integer) –

    Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.

    A value of 0 indicates that the server should never time out.

    The server may reject the proposed value.

    None will cause the server to use its default timeout.

  • coe (bool) –

    Continue on error flag.

    None will cause the server to use its default of False.

  • moc (integer) –

    Maximum number of objects to return for this operation.

    None will cause the server to use its default of 0.
Returns:

instances (list of CIMInstance):

The result set of instances in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.

query_result_class (CIMClass):

Result class definition describing the returned instances, or None.
Return type:

Named tuple, containing the following named items
wbemcli.piwp(ec, moc)[source]

WBEM operation: PullInstancesWithPath

Pull instances from the server as part of an already opened enumeration sequence. This operation can be used as the sequence continuation for OpenEnumerateInstancePaths, OpenAssociatorPaths and OpenReferencePaths.

Parameters:
  • ec (string) – Enumeration context from previous operation response for this enumeration session.
  • moc (integer) – Maximum number of objects to return for this operation.
Returns:

instances (list of CIMInstance):

The result set of instances in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.pip(ec, moc)[source]

WBEM operation: PullInstancePaths

Pull instance paths from the server as part of an already opened enumeration sequence. This operation can be used as the sequence continuation for OpenEnumeratePaths, OpenAssociatorPaths and OpenReferencePaths.

Parameters:
  • ec (string) – Enumeration context from previous operation response for this enumeration session.
  • moc (integer) – Maximum number of objects to return for this operation.
Returns:

paths (list of CIMInstanceName):

The result set of instance paths in response to this request.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.pi(ec, moc)[source]

WBEM operation: PullInstances

Pull instances from the server as part of an already opened enumeration sequence. This operation can be used as the sequence continuation for OpenQueryInstances.

Parameters:
  • ec (string) – Enumeration context from previous operation response for this enumeration session.
  • moc (integer) – Maximum number of objects to return for this operation.
Returns:

instances (list of CIMInstance):

The result set of instances in response to this request. The path attribute is None.

eos (bool):

True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.

context (string):

A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type:

Named tuple, containing the following named items
wbemcli.ce(ec)[source]

WBEM operation: CloseEnumeration

Close an existing open enumeration context early. Once the sequence is complete, the eos flag is set in the last response. Any time before this, the sequence may be closed early with this operation.

Parameters:ec (string) – Enumeration context from previous operation response for this enumeration session.
wbemcli.im(mn, op, *params, **kwparams)[source]

WBEM operation: InvokeMethod

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

Parameters:
  • mn (string) – Method name.
  • op (CIMClassName) – Target instance path.
  • op – Target class path.
  • *params (named args) – Input parameters for the method.
  • **kwparams (keyword args) – Input parameters for the method.
Returns:

Method return value, dict with output parameters.
Return type:

tuple(rv, out)
wbemcli.ecn(ns=None, cn=None, di=None)[source]

WBEM operation: EnumerateClassNames

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

Parameters:
  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.

  • cn (string or CIMClassName) –

    Name of the class whose subclasses are to be enumerated (case independent).

    None will enumerate the top-level classes.

    If specified as a CIMClassName object, its host attribute will be ignored.

  • di (bool) –

    DeepInheritance flag: Include also indirect subclasses.

    None will cause the server default of False to be used.
Returns:

The enumerated class names.
Return type:

list of string
wbemcli.ec(ns=None, cn=None, di=None, lo=None, iq=None, ico=None)[source]

WBEM operation: EnumerateClasses

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

Parameters:
  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.

  • cn (string or CIMClassName) –

    Name of the class whose subclasses are to be enumerated (case independent).

    None will enumerate the top-level classes.

    If specified as a CIMClassName object, its host attribute will be ignored.

  • di (bool) –

    DeepInheritance flag: Include also indirect subclasses.

    None will cause the server default of False to be used.

  • lo (bool) –

    LocalOnly flag: Exclude inherited properties.

    None will cause the server default of True to be used.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    None will cause the server default of True to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    None will cause the server default of False to be used.
Returns:

The enumerated classes.
Return type:

list of CIMClass
wbemcli.gc(cn, ns=None, lo=None, iq=None, ico=None, pl=None)[source]

WBEM operation: GetClass

Retrieve a class.

Parameters:
  • cn (string or CIMClassName) –

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

    If specified as a CIMClassName object, its host attribute will be ignored.

  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.

  • lo (bool) –

    LocalOnly flag: Exclude inherited properties.

    None will cause the server default of True to be used.

  • iq (bool) –

    IncludeQualifiers flag: Include qualifiers.

    None will cause the server default of True to be used.

  • ico (bool) –

    IncludeClassOrigin flag: Include class origin info for props.

    None will cause the server default of False to be used.

  • pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns:

The retrieved class.
Return type:

CIMClass
wbemcli.mc(mc, ns=None)[source]

WBEM operation: ModifyClass

Modify a class.

Parameters:
  • mc (CIMClass) – Modified class.
  • ns (string) –

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

    None will use the default namespace of the connection.
wbemcli.cc(nc, ns=None)[source]

WBEM operation: CreateClass

Create a class in a namespace.

Parameters:
  • nc (CIMClass) – New class.
  • ns (string) –

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

    None will use the default namespace of the connection.
wbemcli.dc(cn, ns=None)[source]

WBEM operation: DeleteClass

Delete a class.

Parameters:
  • cn (string or CIMClassName) –

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

    If specified as a CIMClassName object, its host attribute will be ignored.

  • ns (string) –

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

    If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
wbemcli.eq(ns=None)[source]

WBEM operation: EnumerateQualifiers

Enumerate qualifier types (= declarations) in a namespace.

Parameters:ns (string) –

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

None will use the default namespace of the connection.
Returns:The enumerated qualifier types.
Return type:list of CIMQualifierDeclaration
wbemcli.gq(qn, ns=None)[source]

WBEM operation: GetQualifier

Retrieve a qualifier type (= declaration).

Parameters:
  • qn (string) – Qualifier name (case independent).
  • ns (string) –

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

    None will use the default namespace of the connection.
Returns:

The retrieved qualifier type.
Return type:

CIMQualifierDeclaration
wbemcli.sq(qd, ns=None)[source]

WBEM operation: SetQualifier

Create or modify a qualifier type (= declaration) in a namespace.

Parameters:
  • qd (CIMQualifierDeclaration) – Qualifier type.
  • ns (string) –

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

    None will use the default namespace of the connection.
wbemcli.dq(qn, ns=None)[source]

WBEM operation: DeleteQualifier

Delete a qualifier type (= declaration).

Parameters:
  • qn (string) – Qualifier name (case independent).
  • ns (string) –

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

    None will use the default namespace of the connection.
wbemcli.h()[source]

Print help text for interactive environment.

wbemcli.pdb(stmt)[source]

Run the statement under the PDB debugger.

Development

This section only needs to be read by developers of the pywbem package. People that want to make a fix or develop some extension, and people that want to test the project are also considered developers for the purpose of this section.

Repository

The repository for pywbem is on GitHub:

https://github.com/pywbem/pywbem

Setting up the development environment

The development environment is pretty easy to set up.

Besides having a supported operating system with a supported Python version (see Supported environments), it is recommended that you set up a virtual Python environment.

Then, with a virtual Python environment active, clone the Git repo of this project and prepare the development environment with make develop:

$ git clone git@github.com:pywbem/pywbem.git
$ cd pywbem
$ make develop

This will install all prerequisites the package needs to run, as well as all prerequisites that you need for development.

Generally, this project uses Make to do things in the currently active Python environment. The command make help (or just make) displays a list of valid Make targets and a short description of what each target does.

Building the documentation

The ReadTheDocs (RTD) site is used to publish the documentation for the pywbem package at http://pywbem.readthedocs.io/

This page automatically gets updated whenever the master branch of the Git repo for this package changes.

In order to build the documentation locally from the Git work directory, issue:

$ make builddoc

The top-level document to open with a web browser will be build_doc/html/docs/index.html.

Testing

To run unit tests in the currently active Python environment, issue one of these example variants of make test:

$ make test                                              # Run all unit tests
$ PYTHONPATH=. py.test testsuite/test_cim_obj.py -s      # Run only this test source file
$ PYTHONPATH=. py.test InitCIMInstanceName -s            # Run only this test class
$ PYTHONPATH=. py.test -k InitCIMInstanceName or Bla -s  # py.test -k expressions are possible

Invoke py.test --help for details on the expression syntax of its -k option.

To run the unit tests and some more commands that verify the project is in good shape in all supported Python environments, use Tox:

$ tox                              # Run all tests on all supported Python versions
$ tox -e py27                      # Run all tests on Python 2.7

Contributing

Third party contributions to this project are welcome!

In order to contribute, create a Git pull request, considering this:

  • Test is required.
  • Each commit should only contain one “logical” change.
  • A “logical” change should be put into one commit, and not split over multiple commits.
  • Large new features should be split into stages.
  • The commit message should not only summarize what you have done, but explain why the change is useful.
  • The commit message must follow the format explained below.

What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.

For further discussion of good and bad practices regarding commits, see:

Appendix

This section contains information that is referenced from other sections, and that does not really need to be read in sequence.

Special type names

This documentation uses a few special terms to refer to Python types:

string
a unicode string or a byte string
unicode string
a Unicode string type (unicode in Python 2, and str in Python 3)
byte string
a byte string type (str in Python 2, and bytes in Python 3). Unless otherwise indicated, byte strings in pywbem are always UTF-8 encoded.
number
one of the number types int, long (Python 2 only), or float.
integer
one of the integer types int or long (Python 2 only).
callable
a type for callable objects (e.g. a function, calling a class returns a new instance, instances are callable if they have a __call__() method).
DeprecationWarning
a standard Python warning that indicates a deprecated functionality. See section Deprecation policy and the standard Python module warnings for details.
Element
class xml.dom.minidom.Element. Its methods are described in section Element Objects of module xml.dom, with minidom specifics described in section DOM Objects of module xml.dom.minidom.
CIM data type
one of the types listed in CIM data types.
CIM object
one of the types listed in CIM objects.

Troubleshooting

Here are some trouble shooting hints for the installation of pywbem.

AttributeError for NullHandler during mkvirtualenv on Python 2.6

If the mkvirtualenv command fails on Python 2.6 with this error:

File "/usr/lib/python2.6/site-packages/stevedore/__init__.py", line 23,
  in <module> LOG.addHandler(logging.NullHandler())
AttributeError: 'module' object has no attribute 'NullHandler'

then the stevedore PyPI package is too recent(!) The owners of that package spent effort to remove the previously existing Python 2.6 support in some steps, starting with stevedore v1.10.

The solution is to use stevedore v1.9. Note that for virtualenvwrapper to use it, it must be installed into the system Python:

$ sudo pip install stevedore==1.9

TypeError about StreamHandler argument ‘stream’ during mkvirtualenv on Python 2.6

If the mkvirtualenv command fails on Python 2.6 with this error:

File "/usr/lib/python2.6/site-packages/virtualenvwrapper/hook_loader.py",
  line 101, in main
console = logging.StreamHandler(stream=sys.stderr)
TypeError: __init__() got an unexpected keyword argument 'stream'

then the virtualenvwrapper PyPI package is too old. As of its released version v4.7.1, a fix for that is in the master branch of its repository and has not been released yet.

While a new version of virtualenvwrapper with the fix is not yet released, a solution is to clone the virtualenvwrapper repository and to install it from its working directory. Note that it must be installed into the system Python:

$ git clone https://bitbucket.org/dhellmann/virtualenvwrapper.git virtualenvwrapper
$ cd virtualenvwrapper
$ sudo python setup.py install

Swig error ‘Unrecognized option -builtin’ during M2Crypto install

On Python 2.x, pywbem uses the M2Crypto package from PyPI and installs it during its own installation. The M2Crypto package invokes the Swig tool during its installation. If the version of Swig is too old, the invocation of Swig fails with:

swig error : Unrecognized option -builtin

The solution is to use Swig v2.0 or higher.

The pywbem setup script checks the version of Swig and installs a newer version of Swig, or if not available builds Swig from its sources (while automatically installing any further OS-level prerequisites needed for building Swig).

gcc does not find Python.h while installing M2Crypto

On Python 2.x, pywbem uses the M2Crypto package from PyPI and installs it during its own installation. The M2Crypto package invokes the Swig tool during its installation. Swig invokes the gcc compiler on source code it produces. That source code needs the Python.h header file.

If the invocation of gcc fails with:

SWIG/_m2crypto_wrap.c:127:20: fatal error: Python.h: No such file or directory

then you do not have the Python.h header file available.

The installation of pywbem with OS-level prereqs (see Installation) installs the necessary Python SDK package for C/C++ (or displays its package name). On RHEL, the missing package is python-dev.

Glossary

dynamic indication filter
dynamic filter
An indication filter in a WBEM server whose life cycle is managed by a client. See DSP1054 for an authoritative definition and for details.
static indication filter
static filter
An indication filter in a WBEM server that pre-exists and whose life cycle cannot be managed by a client. See DSP1054 for an authoritative definition and for details.

Change log

This version of the documentation is development version 0.10.1 and contains the master branch up to this commit:

  • Merge pull request #777 from pywbem/release_0.10.1 by Andreas Maier at 2017-09-27 23:18:07

    Release v0.10.1

pywbem v0.10.1

Released: 2017-09-27

Incompatible changes

None

Enhancements

  • Added support for automatically finding out whether for RHEL/CentOS/Fedora, the IUS version of the Python development packages should be used, dependent on whether the Python package is from IUS.
  • Ensured that CIMDateTime objects for point in time values are timezone-aware when supplied with a timezone-naive datetime object. This does not change the behavior, but increases code clarity. Clarified that in the documentation of CIMDateTime. See issue #698.

Bug fixes

  • Fix issue with MaxObjectCount on PullInstances and PullInstancePaths CIM_Operations.py methods. The MaxObjectCount was defined as a keyword parameter where it should have been be positional. This should NOT impact clients unless they did not supply the parameter at all so that the result was None which is illegal(Pull... operations MUST include MaxObjectCount). In that case, server should return error. Also extends these requests to test the Pull.. methods for valid MaxObjectCount and context parameters. See issue #656.
  • Fixed TypeError “‘str’ does not support the buffer interface” during ‘setup.py develop’ on Python 3.x on Windows (issue #661).
  • Fixed ValueError “underlying buffer has been detached” during ‘setup.py develop’ on Python 3.x on Windows (issue #661).
  • Fixed names of Python development packages for SLES/OpenSUSE.
  • Fixed that older versions of pip and setuptools failed or were rejected on some older Linux distros during make develop or make install, by upgrading them in these steps. See issues #759 and #760.

Build, test, quality

  • Added Python 3.6 to the environments to be tested in Travis CI and Appveyor CI (issue #661).
  • Added Python 2.6, 3.4 and 3.5 to the environments to be tested in Appveyor CI (issue #661).
  • Fixed uninstall_pbr_on_py26.py to remove ‘pbr’ only if installed (issue #661).
  • Fixed TypeError about dict ordering on Python 3.6 in unit test ‘test_nocasedict.TestOrdering’ (issue #661).
  • Tolerated incorrect Unicode characters in output of commands invoked by os_setup.py (used for installation) that sometimes occurred on Windows (e.g. on the Appveyor CI with Python 3).
  • Pinned the version of the wheel package to <0.30.0 for Python 2.6, because wheel removed Python 2.6 support in its 0.30.0 version.
  • Improved the build process to ensure that half-built artefacts are removed before building (issue #754).

Documentation

  • Documented that pywbem is not supported on Python 2.6 on Windows. and that 64-bit versions of Python are not supported on Windows.

pywbem v0.10.0

Released: 2016-12-20

Incompatible changes

  • All methods of the WBEMSubscriptionManager class that returned instance paths (or lists thereof) in pywbem v0.9 now return the complete instances (or lists thereof) (pr #607).
  • In wbemcli, removed the long global function names (e.g. EnumerateInstances), and kept the short names (e.g. ei) (issue #548).

Enhancements

  • Experimental: Added new methods to WBEMConnection to provide integrated APIs for the non-pull and pull operations, reducing the amount of code app writers must produce and providing a pythonic (generator based) interface for the methods that enumerate instances and instance paths, enumerator associators and references. These new methods have names in the pattern Iter<name of original function>. Thus, for example the new method IterEnumerateInstances creates a new API to integrate EnumerateInstances and the OpenEnumerateInstancesWithPath / PullInstancesWithPath. (issue #466).

  • Modified the XML parser to use SAX in place of minidom for operation response processing and indication processing. This is a significant reduction in memory usage (issue #498).

  • Declared the WBEM indications API and the WBEM server API to be final. These APIs had been introduced in v0.9.0 as experimental.

  • Added enter and exit methods to WBEMSubscriptionManager to enable using it as a context manager, whose exit method automatically cleans up by calling remove_all_servers() (issue #407).

  • Added methods to the operation recorder (class BaseOperationRecorder) for disabling and enabling it (issue #493).

  • The “Name” property of indication filters created via the WBEMSubscriptionManager class can now be controlled by the user (pr #607).

  • Indication filter, listener destination and indication subscription instances created via the WBEMSubscriptionManager class, that are “owned”, are now conditionally created, dependent on the owned instances that have been discovered upon restart of the WBEMSubscriptionManager (pr #607).

  • Modified operations that have a “PropertyList” attribute to allow the “PropertyList” attribute to have a single string in addition to the iterable. Previously this caused an XML error (issue #577).

  • Added an option -s / –script to wbemcli that supports executing scripts in the wbemcli shell.

    Some example scripts are provided in the examples directory:

    • wbemcli_server.py - Creates a WBEMServer object named SERVER representing a WBEM server.
    • wbemcli_quit.py - Demo of terminating wbemcli from within a script.
    • wbemcli_display_args.py - Demo of displaying input arguments.
    • wbemcli_count_instances.py - Counts classes and instances in a server.
    • wbemcli_clean_subscriptions.py - Removes all subscriptions, filters, and listener destination instances in a server.
    • test_wbemcli_script.sh - A shell script that demos scripts.

  • Improved robustness and diagnostics in os_setup.py (issue #556).

Bug fixes

  • Fixed the use of a variable before it was set in the remove_destinations() method of class WBEMSubscriptionManager.
  • Fixed a compatibility issue relative to pywbem 0.7.0, where the pywbem.Error class was no longer available in the pywbem.cim_http namespace. It has been made available in that namespace again, for compatibility reasons. Note that using sub-namespaces of the pywbem namespace such as pywbem.cim_http has been deprecated in pywbem 0.8.0 (issue #511).
  • Fixed an AttributeError in the remove_all_servers() method of WBEMSubscriptionManager and dictionary iteration errors in its remove_server() method (pr #583).
  • Fixed a TypeError in the TestClientRecorder operation recorder that occurred while handling a ConnectionError (this recorder is used by the –yamlfile option of run_cim_operations.py) (issue #587).
  • Fixed several errors in recorder on Python 3 (issue #531).
  • In wbemcli, several fixes in the short global functions (issue #548).
  • Fixed name of python devel package for Python 3.4 and 3.5.
  • Several changes, fixes and improvements on WBEMSubscriptionManager (issues #462, #540, #618, #619).
  • Added a check for unset URL target in recorder (issue #612).
  • Fixed access to None in recorder (issue #621)

Build, test, quality

  • Added flake8 as an additional lint tool. It is executed with make check. Fixed all flake8 issues (issues #512, #520, #523, #533, #542, #560, #567, #575).
  • Changed names of the pylint and flake8 config files to match the default names defined for these utilities (pylintrc and .flak8) (issue #534).
  • Added CIM Schema archive to the repository, in order to avoid repeated downloads during testing in the CI systems (issue #49).
  • Added git as an OS-level dependency for development (it is used by GitPython when building the documentation) (pr #581).
  • Added wheel as a Python dependency for development. This package is not installed by default in some Linux distributions such as CentOS 7, and when installing into the system Python this becomes an issue (pr #622).
  • Added retry in setup script to handle xmlrpc failures when installing prerequisites from PyPI.
  • Fixed logic errors in pycmp compatibility checking tool.
  • Changed makefile to skip documentation build on Python 2.6 due to Sphinx having removed Python 2.6 support (issue #604).
  • Fixed UnboundLocalError for exc in setup.py (issue #545).
  • Added an executable run_enum_performance.py to the testsuite to test pull performance. It generates a table of the relative performance of EnumerateInstances vs. OpenEnumerateInstances / PullInstancesWithPath performance over a range of MaxObjectCount, response instance sizes, and total number of instances in the response.
  • Completed the test_client.py mock tests for all instance operations.
  • Improved the tests in run_cim_operations.py.

Documentation

  • Added the global functions available in the wbemcli shell to the documentation (issue #602).
  • Improved usage information for the “Tutorial” section, to make usage of Jupyter tutorials more obvious (issue #470).
  • Added “Installation” and “Development” sections to the documentation, and moved some content from the “Introduction” section into a new “Appendix” section. Added an installation trouble shooting section to the appendix (pr #509).
  • Added a section “Prerequisite operating system packages” to the documentation that describes the prerequisite packages by distribution (pr #549).
  • Fixed a documentation build error on Python 2.6, by pinning the GitPython version to <=2.0.8, due to its use of unittest.case which is not available on Python 2.6 (issue #550).
  • Clarified the behavior for the default WBEMConnection timeout (None) (issue #628).
  • Fixed a documentation issue where the description of CIMError was not clear that the exception object itself can be accessed by index and slice (issue #511).
  • Added the wbemcli global functions to the documentation (issue #608).

pywbem v0.9.0

Released: 2016-09-06

Deprecations

  • Deprecated the use of the value instance variable and ctor parameter of the CIMParameter class, because that class represents CIM parameter declarations, which do not have a default value. Accessing this instance variable and specifying an initial value other than None now causes a DeprecationWarning to be issued.
  • Deprecated ordering comparisons for NocaseDict, CIMInstance, CIMInstanceName, and CIMClass objects. This affects the ordering comparisons between two such objects, not the ordering of the items within such a dictionary. Use of ordering operators on objects of these classes now causes a DeprecationWarning to be issued.
  • Deprecated the methodname input argument of CIMMethod(), and renamed it to name. methodname still works but its use causes a DeprecationWarning to be issued.
  • Deprecated the use of the verify_callback parameter of WBEMConnection. because it is not used with the Python ssl module and will probably be removed completely in the future. Its use now causes a DeprecationWarning to be issued. (Issue #297)

Known Issues

  • Installing PyWBEM on Python 2.6 has a conflict with the pbr package from PyPI, resulting in a TypeError: “dist must be a Distribution instance”. This issue is specific to Python 2.6 and does not occur in any of the other supported Python versions (2.7, 3.4, 3.5). This issue can be mitigated by uninstalling the pbr package, or if that is not possible, by migrating to Python 2.7. See issue #26 on GitHub.
  • MOF using names that are reserved keywords will fail to compile in the MOF compiler. For example, a CIM property named ‘indication’. See issue #62 on GitHub.

Clean Code

  • Moved the following unused modules from the pywbem package directory into a new attic directory, in order to clean up the pywbem package:
    • cim_provider.py
    • cim_provider2.py
    • cimxml_parse.py
    • test_cimxml_parse.py
    • twisted_client.py
  • Moved the script-related portions of the pywbem/mof_compiler.py module into the mof_compiler script.
  • Moved the complete pywbem/wbemcli.py module into the wbemcli script.
  • Removed half-baked code for HTTP proxy/tunneling support.

Enhancements

  • Implemented pull operations per DMTF specification DSP0200 and DSP0201. This includes the following new client operations to execute enumeration sequences:

    • OpenEnumerateInstances
    • OpenEnumerateInstancePaths
    • OpenAssociatorInstances
    • OpenAssociatorInstancePaths
    • OpenReferenceInstances
    • OpenReferenceInstancePaths
    • OpenQueryInstances
    • PullInstances
    • PullInstancesWithPath
    • PullInstancePaths
    • CloseEnumeration

    The EnumerationCount operation is NOT implemented, because it is both deprecated and unusable. (Issue #9)

    Unit tests of the pull operations are included and mock tests are written for at least some parts of the pull operations.

  • Implemented support for reading information from WBEM servers according to the DMTF WBEM Server Profile (DSP1071) and DMTF Profile Registration Profile (DSP1033) with a new WBEMServer class. Note that not everyhting in these profiles needs to be implemented in the WBEM server for this to work:

    • The WBEMServer class is a client’s view on a WBEM server and provides consistent and convenient access to the common elements of the server, including namespace names, interop namespace name, registered profile information, server branding, and central/scoping class algorithms.
    • Added unit tests for this new class in run_cim_operations.py and test_client.py.
    • Added a demo of the discovery abilities of the WBEMServer class in the examples/explore.py script.

    Experimental - This new class is experimental for pywbem version 0.9.0 because this is the initial release of a significant change and subject to changes to the API.

    (Issues #9, #346, #468)

  • Implemented support for WBEM subscription management and a WBEM indication listener:

    • Added a WBEMListener class that allows the creation of a listener entity to receive indications.
    • Added a WBEMSubscriptionManager class that allows management of indication subscriptions, indication filters, and listener destination instances on the WBEM Server using the new WBEMServer class.
    • Added unit tests for these new classes and extended other existing tests accordingly, e.g. run_cim_operations.py.

    Experimental - These new classes are experimental for pywbem version 0.9.0 because this is the initial release of a significant change and subject to changes to the API.

    (Issues #66, #421, #414, #379, #378)

  • The distribution formats released to PyPI have been extended. There are now:

    • Source archive (existed)
    • Universal wheel (new)

    (Issue #242)

  • Starting with v0.9.0, pywbem no longer stores the distribution archives in the repository, because the process for releasing to PyPI creates new distribution archives instead of using the created ones. This makes it difficult to ensure that the archives stored in the repository are the same.

  • Upgraded M2Crypto to use official 0.24.0 from PyPI.

  • Added check for minimum Python version 3.4 when running on Python 3. That requirement was already documented, now it is also enforced in the code.

  • Migrated API documentation to Sphinx.

  • Improved documentation of many classes of the external API.

  • Replaced [] and {} default arguments with None.

  • Changed the return value of repr() for WBEMConnection, CIM type classes (e.g. Sint8, CIMDateTime), and CIM object classes (e.g. CIMInstance) so that they now return all attributes in a reasonable order, and are suitable for debugging.

  • Clarified in the description of CIMClassName.__str__() and CIMInstanceName.__str__() that they return the WBEM URI representation of the class path and instance path.

  • Changed the return value of str() for CIM object classes (e.g. CIMProperty) so that they now return a short set of the most important attributes for human consumption. Specifically, this resulted in the following changes:

    • For CIMProperty, reduced the complete set of attributes to a short set.
    • For CIMQualifierDeclaration, added the attribute value.

  • Changes in the CIMError exception class:

    • Changed the behavior of the __str__() method to return a human readable string containing the symbolic name of the status code, and the status description. The previous behavior was to return a Python representation of the tuple status code, status description.
    • Added properties status_code (numeric CIM status code), status_code_name (symbolic name of CIM status code), and status_description (CIM status description).
    • Updated the documentation to no longer show the unused third tuple element exception_obj. It was never created, so this is only a doc change.

  • Added CIM status codes 20 to 28, specifically to support the pull operations.

  • Changed the ParseError exception to be derived from the Error base exception, so that now all pywbem specific exceptions are derived from Error.

  • Added tocimxmlstr() as a global function and as methods on all CIM object classes. It returns the CIM-XML representation of the object as a unicode string either in a single-line variant, or in a prettified multi-line variant.

  • Created tomof() for CIMProperty making common functionality available to both class and instance tomof() (PR #151)

  • Added an optional namespace parameter to the WBEMConnection.CreateInstance() method, for consistency with other methods, and to have an explicit alternative to the namespace in the path component of the NewInstance parameter.

  • The ClassName parameter of several operation methods can be specified as both a string and a CIMClassName object. In the latter case, a namespace in that object was ignored so far. Now, it is honored. This affects the following WBEMConnection methods: EnumerateInstanceNames, EnumerateInstances, EnumerateClassNames, EnumerateClasses, GetClass, DeleteClass.

  • Enhanced the CIM integer data types (e.g. pywbem.Uint8()) to accept all input parameters that are supported by int().

  • Added the concept of a valid value range for the CIM integer data types, that is enforced at construction time. For compatibility, this strict checking can be turned off via a config variable: pywbem.config.ENFORCE_INTEGER_RANGE = False.

  • Extended wbemcli arguments to include all possible arguments that would be logical for a ssl or non-ssl client. This included arguments for ca certificates, client keys and certificates, timeout. It also modifies the server argument to use http:// or https:// prefix and suffix with :<port number> and drops the old arguments of –port and –no-ssl

  • Improved Swig installation code by reinstalling Swig if it was installed but still cannot be found in PATH (e.g. if the installation was tampered with).

  • Removed dependency on git (this was a leftover from when M2Crypto needed to be obtained from its development repo).

  • Added debug prints for two probably legitimate situations where socket errors are ignored when the server closes or resets the connection. These debug prints can be enabled via the debug instance variable of the WBEMConnection object; they are targeted at development for investigating these situations.

  • Extended run_cim_operations.py which is a live test against a server. It has only been tested against OpenPegasus but was extended to cover more details on more of the operation types and to create a test subclass to specifically test against OpenPegasus if OpenPegasus is detected as the server.

  • Added description of supported authentication types in WBEM client API.

  • Allowed tuple as input for PropertyList parameter of WBEMConnection operation methods. Documentation indicated that iterable was allowed but was limited to list. (Issue #347)

  • Added a tutorial section to the generated documentation, using Jupyter Notebooks for each tutorial page. (Issue #324)

  • Added the concept of operation recording on WBEM connections, that supports user-written operation recorders e.g. for tracing purposes. Added an operation recorder that generates test cases for the test_client unit test module. (Issue #351)

  • Extended wbemcli for all pull operations. (Issue #341)

  • Changed command line options of mof_compiler command to be consistent with wbemcli, and added support for specifying certificate related options. use of the old options is checked and causes an according error message to be displayed. Note, this is an incompatible change in the command line options. (Issue #216)

  • Cleaned up exception handling in WBEMConnection methods: Authentication errors are now always raised as pywbem.AuthError (OpenWBEM raised pywbem.ConnectionError in one case), and any other bad HTTP responses are now raised as a new exception pywbem.HTTPError.

  • Clarified MofParseError by defining attributes as part of the class init and moving some code from productions to the class itself (Issue #169). This makes the MofParseError exception more suitable for use from the productions themselves. The original definition was really only for use as a call from ply. Add tests for invalid qualifier flavors to unit tests and add test in mof_compiler.py for conflicting flavors ex. tosubclass and restricted in the same definition. This test uses the new MofParseError. (Issue #204)

  • Extended PropertyList argument in request operations to be either list or tuple. (Issue #347)

  • Added support for representing control characters in MOF strings using MOF escape sequences, e.g. U+0001 becomes “x0001”.

  • Modified qualifier MOF output to stay within 80 column limits. (Issue #35)

Bug fixes

  • Fixed KeyError when iterating over CIMInstance and CIMInstanceName objects.
  • Fixed bug that MOF escape sequences in strings were passed through unchanged, into generated MOF, by removing needless special-casing code.
  • Fixed bug with class MOF generation where output was not including array indicator ([]). (Issue #233)
  • Moved class property MOF output processing to CIMProperty and fixed issue where default values were not being generated. (Issues #223 and #231)
  • Fixed bug in method MOF output where array flag “[]” was left off array parameters.
  • In the WBEMConnection.ModifyInstance() method, the class names in the instance and path component of the ModifiedInstance parameter are required, but that was neither described nor checked. It is now described and checked.
  • In the WBEMConnection.ModifyInstance() method, a host that was specified in the path component of the ModifiedInstance parameter incorrectly caused an INSTANCEPATH element to be created in the CIM-XML. This bug was fixed, and a host is now ignored.
  • Fixed a bug where the CIM datetime string returned by the str() function on CIMDateTime interval objects contained incorrect values for the minutes and seconds fields on Python 3. (Issue #275).
  • Fixed an IndexError in cim_http.wbem_request() that occurred during handling of another exception.
  • Fixed issue with Python 3 and https that was causing connect() to fail. This completely separates connect() code for Python 3 ssl module from Python 2 M2Crypto.
  • Fixed problem that wbemcli in Python 3 when used without existing history file would fail with “TypeError: ‘FileNotFoundError’ object is not subscriptable”. (Issue #302)
  • Fixed issue with tomof() output where datetime values were not quoted. (Issue #289)
  • Eliminated automatic setting of toinstance flavor in mof_compiler when tosubclass is set. Also enabled use of toinstance flavor if defined in a class or qualifier declaration. (Issue #193)
  • Fixed problem in class-level associator operations that namespace was classname when classname was passed as a string. (Issue #322)
  • Fixed hole in checking where class CIMMethod allowed None as a return_type. (Issue #264)
  • Fixed a documentation issue with associators/references return types. It was documented as a list of classes for class level return, but it actually is a list of tuples of classname, class. (Issue #339)
  • Created a common function for setting SSL defaults and tried to create the same level of defaults for both Python2 (M2Crypto) and Python 3 (SSL module). The minimum level protocol set by the client is TLSV1 now whereas in previous versions of pywbem it was SSLV23. (Issue #295)
  • Fixed issue where mof_compiler was setting values for compile of instances into the class object and also setting the values for the last compiled instance in a compile unit into all other compiled instances for the same class. Since the concept of compiling a path into compiled instances is flawed (there is no requirement to include all properties into a instance to compile that code was removed so that the path is NOT build into a compiled instance. Finally the qualifiers from the class were also included in compiled instances which was incorrect and an accident of the code. They are no longer included into the compiled instances.) (Issue #402)
  • Fixed description in INSTALL.md to correctly describe how to establish OS-level prerequisites.
  • Cleaned up the timeouts on SSL and created specific tests for timeouts against a live server. (Issues #363, #364)

pywbem v0.8.4

Released: 2016-05-13

Bug fixes

  • Fixed an IndexError in cim_http.wbem_request() that occurred during handling of another exception.
  • Fixed problem that wbemcli in Python 3 when used without existing history file would fail with “TypeError: ‘FileNotFoundError’ object is not subscriptable” (issue #302).
  • Fixed issues with Python 3 and HTTPS that were causing the connecttion to fail. This completely separates the connect() code for Python 3 (using the Python SSL module) from the code for Python 2 (using M2Crypto) (issues #150, #273, #274, #288).

Enhancements

  • Improved description in INSTALL.md to better describe how to establish OS-level prerequisites.
  • Improved Swig installation code by reinstalling Swig if it was installed but still cannot be found in PATH (e.g. if the installation was tampered with).
  • Removed dependency on git (this was a leftover from when M2Crypto needed to be obtained from its development repo).
  • Added debug prints for two probably legitimate situations where socket errors are ignored when the server closes or resets the connection. These debug prints can be enabled via the debug instance variable of the WBEMConnection object; they are targeted at development for investigating these situations.
  • Added check for minimum Python version 3.4 when running on Python 3. That requirement was already documented, now it is also enforced in the code.
  • Enhanced the wbemcli script with options supporting certificates. For details, invoke with –help, or look at the online documentation. NOTE: The –no-ssl and –port options have been removed. Specify the protocol and port number in the server URL.

Clean code

  • Removed half-baked code for HTTP proxy/tunneling support.

pywbem v0.8.3

Released: 2016-04-15

Bug fixes

  • To address some M2Crypto issues, upgraded to use M2Crypto >=0.24 from PyPI.
  • For Windows, using M2CryptoWin32/64 >=0.21 from PyPI, in order to avoid the Swig-based build in Windows.
  • Improved the mechanism to build the LEX/YACC table modules, so that import errors for freshly installed packages (e.g. M2Crypto) no longer occur.

Enhancements

  • Added Windows versions of WBEM utility commands: wbemcli.bat, mof_compiler.bat.

pywbem v0.8.2

Released: 2016-03-20

Bug Fixes

  • Eliminated dependency on six package during installation of pywbem. (Andreas Maier)

Dependencies

  • v0.8.x has the following dependencies on other PyPI packages (see install_requires argument in setup script):
    • M2Crypto
    • ply
    • six

pywbem v0.8.1

Released: 2016-03-18

Known Issues

  • Installing PyWBEM on Python 2.6 has a conflict with the pbr package from PyPI, resulting in a TypeError: “dist must be a Distribution instance”. This issue is specific to Python 2.6 and does not occur in any of the other supported Python versions (2.7, 3.4, 3.5). This issue can be mitigated by uninstalling the pbr package, or if that is not possible, by migrating to Python 2.7. See issue #26 on GitHub.
  • MOF using names that are reserved keywords will fail to compile in the MOF compiler. For example, a CIM property named ‘indication’. See issue #62 on GitHub.
  • The Pulled Enumeration Operations introduced in DSP0200 1.3 are not supported in this release. See issue #9 on GitHub.
  • Note that some components of this PyWBEM Client package are still considered experimental:
    • The twisted client module twisted_client.py.
    • The Python provider modules cim_provider.py and cim_provider2.py.
    • The CIM indication listener in the irecv directory. See issue #66 on GitHub.

Changes

  • The MOF compiler is now available as the command ‘mof_compiler’ that gets installed into the Python script directory. It is now separate from the ‘mof_compiler’ module within the ‘pywbem’ package. In 0.7.0, the module was at the same time the script. (Andreas Maier)
  • The WBEM client CLI is now available as the command ‘wbemcli’ that gets installed into the Python script directory. It is now separate from the ‘wbemcli’ module within the ‘pywbem’ package. In 0.7.0, the module was at the same time the script. (Andreas Maier)
  • In 0.7.0, most symbols defined in the sub-modules of the ‘pywbem’ package were folded into the ‘pywbem’ package namespace, cluttering it significantly. The symbols in the ‘pywbem’ package namespace have been reduced to a well-defined set that is now declared the external API of the WBEM client library, and is supposed to be sufficient. If you find that you need something you were used to, please think twice as to whether that makes sense to be part of the external PyWBEM API, and if so, let us know by opening an issue.
  • Since 0.7.0, some exceptions that can be raised at the external API of the WBEM client library have been cleaned up.

Enhancements

  • Verify certificates against platform provided CA trust store in /etc/pki/tls/certs. Linux only. (Peter Hatina)
  • Added ‘-d’ option to MOF compiler that causes the compiler to perform a dry-run and just check the MOF file syntax. This allows to more easily detect included MOF files when used together with the ‘-v’ option. (Jan Safranek)
  • Added support for non-ASCII (Unicode) characters. (Michal Minar, Andreas Maier)
  • Improved information in the message text of some exceptions (TypeError and KeyError in cim_obj.py, ValueError in cim_obj.py, and ParseError in tupleparse.py). (Andreas Maier)
  • Moved the definition of the pywbem version from setup.py to __init__.py, in order to make it available to programs using pywbem as pywbem.__version__. (Andreas Maier)
  • Added support for direct iteration over NocaseDict objects using for and in by adding __iter__(), e.g. for use with CIMInstance.properties. (Andreas Maier)
  • Added more instance attributes to be shown in repr() on CIMProperty and other classes in cim_obj. (Andreas Maier)
  • Added and improved docstring-based documentation in the pywbem modules cim_operations, cim_http, cim_obj, cim_types, and the pywbem module. (Andreas Maier)
  • Improved the way missing file:// URL support on Windows is handled, by now issuing a proper error message instead of stumbling across the missing socket.AF_UNIX constant. (Andreas Maier)
  • Improved the way missing OWLocal authorization with the OpenWBEM server is handled on Windows, by now issuing a proper error message instead of stumbling across the missing os.getuid() function. (Andreas Maier)
  • Improved Windows portability by no longer attempting to import pwd in case the userid is not set in the environment variables that are checked when the WBEM server is local. (Andreas Maier)
  • Added support for ExecQuery operation to twisted client. (Robert Booth)
  • Added get() methods on CIMInstance and CIMInstanceName to step up to the statement that they behave like dictionaries w.r.t. properties and key bindings. (Andreas Maier)
  • Improved help text of test_cim_operations.py test program. (Andreas Maier)
  • Added an optional Params argument to InvokeMethod(), that is an ordered list of CIM input parameters, that preserves its order in the CIM-XML request message. This is to accomodate deficient WBEM servers that do not tolerate arbitrary order of method input parameters as required by the standard. The new argument is optional, making this a backwards compatible change of InvokeMethod(). (Andreas Maier)
  • Cleaned up the public symbols of each module by making symbols private that are used only internally. Specifically, the following symbols have been made private: In cimxml_parse: _get_required_attribute, _get_attribute, _get_end_event, _is_start, _is_end. In cim_xml: _text (was: Text). (Andreas Maier)
  • Cleaned up symbols imported by wildcard import by defining __all__ in each module with only the public symbols defined in that module (removing any symbols imported into the module), except for the following modules which define less than the complete set of public symbols in their __all__: mof_compiler, twisted_client, tupleparse, cimxml_parse, cim_http. (Andreas Maier)
  • Added support for using CDATA section based escaping in any requests sent to the WBEM server. The default is still XML entity reference based escaping, the CDATA based escaping can be turned on by setting the switch _CDATA_ESCAPING accordingly, which is a global variable in the cim_xml module. (Andreas Maier)
  • Simplified the exceptions that can be raised by WBEMConnection methods, and improved the information in the exception messages. See description of WBEMConnection class for details. (Andreas Maier)
  • Added support for timeouts to WBEMConnection, via a new timeout argument, that defaults to no timeout. (This finally increased the minimum version of Python to 2.6. (Andreas Maier)
  • Improved installation process of PyWBEM, particularly related to M2Crypto. (Andreas Maier)
  • Added support for Python 3. Issue #3 on GitHub. (Ross Peoples, Andreas Maier)

Bug Fixes

  • Fix syntax error in CIM DTDVERSION error path. Allow KEYVALUE VALUETYPE attribute to be optional as specified in the DTD. (Andreas Linke)
  • Added parsing of InvokeMethod return value and output parameters for Twisted Python client. (Tim Potter)
  • Fixed cim_provider2.py to properly support shutdown() and can_unload() (called from CMPI cleanup() functions). Support was recently added to cmpi-bindings for this. (Bart Whiteley)
  • Fixed XML parsing to accept SFCB-style embedded instance parameters. (Mihai Ibanescu)
  • Use getpass module instead of pwd to detect local user to fix Win32. (Tim Potter)
  • Re-throw KeyError exceptions with capitalised key string instead of lower cased version in NocaseDict.__getitem__(). (Tim Potter)
  • Use base64.b64encode() instead of base64.encodestring() in Twisted client. (Mihai Ibanescu)
  • Fix missing CIMDateTime import in Twisted client. (Mihai Ibanescu)
  • Fixed CIMInstanceName rendering to string. It is now possible to pass the rendered string value as an instance path argument of a CIM method. (Jan Safranek, Michal Minar)
  • For Python providers, fixed the comparsion of the Role parameter in association operations to be case insensitive, and removed an erroneous test that raised an exception when the property specified in the Role parameter was not also in the property list specified by the Properties parameter. (Jan Safranek)
  • For Python providers, converted debug ‘print’ statements to trace messages that end up in the system log. (Jan Safranek)
  • The CIM-XML parser no longer throws an exception when parsing a qualifier declaration. Note: The CIM-XML supported by this fix does not conform to DSP0201 so far. Further fixes are pending. (Jan Safranek)
  • Fixed parsing errors for connection URLs with IPv6 addresses, including zone indexes (aka scope IDs). (Peter Hatina, Andreas Maier)
  • Fixed the hard coded socket addressing family used for HTTPS that was incorrect in some IPv6 cases, by determining it dynamically. (Peter Hatina)
  • Fixed the list of output parameters of extrinsic method calls to be returned as a case insensitive dictionary (using cim_obj.NocaseDict). (Jan Safranek)
  • Fixed the checking of CIMVERSION attributes in CIM-XML to only verify the major version, consistent with DSP0201 (see subclause 5.2.1, in DSP0201 version 2.3.1). (Jan Safranek)
  • Fixed error in cim_http.py related to stronger type checking of Python 2.7. (Eduardo de Barros Lima)
  • Removed erroneous qualifier scopes SCHEMA and QUALIFIER from the MOF compiler (see DSP0004). (Andreas Maier)
  • Fixed debug logging of CIM-XML payload (that is, conn.last_*request/reply attributes) for extrinsic method calls, to now be consistent with intrinsic method calls. (Andreas Maier)
  • Fixed TOCTOU (time-of-check-time-of-use) error when validating peer’s certificate. (Michal Minar)
  • Added a check in the CIMInstanceName constructor that the classname argument is not None. (Andreas Maier)
  • Fixed the issue in the CIMProperty constructor that specifying a tuple for the value argument was incorrectly detected to be a scalar (and not an array). (Andreas Maier)
  • Fixed the issue in the CIMProperty constructor that specifying a datetime or timedelta typed value resulted in storing the provided object in the value attribute, instead of converting it to a CIMDateTime object. (Andreas Maier)
  • Fixed the issue in the CIMProperty constructor that specifying a datetime formatted string typed value argument along with type=’datetime’ resulted in storing the provided string object in the value attribute, instead of converting it to a CIMDateTime object. (Andreas Maier)
  • Fixed several cases in the CIMProperty constructor of unnecessarily requiring the optional arguments type, is_array, embedded_object, or reference_class. These optional arguments are now only necessary to be provided if they cannot be implied from provided arguments (mainly from value). (Andreas Maier)
  • Fixed the issue in the CIMProperty constructor that an embedded_object argument value of ‘object’ was changed to ‘instance’ when a CIMInstance typed value argument was also provided. (Andreas Maier)
  • Fixed the issue in the CIMProperty constructor that the first array element was used for defaulting the type attribute, without checking that for None, causing an exception to be raised in this case. (Andreas Maier)
  • Added a check in the CIMProperty constructor that the name argument is not None. (Andreas Maier)
  • Fixed the issue that the CIMProperty constructor raised only TypeError even when the issue was not about types; it now raises in addition ValueError. (Andreas Maier)
  • Changed the exception that is raised in NocaseDict.__setitem__() for invalid key types, to be TypeError in instead of KeyError. Updated the testcases accordingly. (Andreas Maier)
  • Added checks for more than one argument and for unsupported argument types to the constructor of NocaseDict. (Andreas Maier)
  • Fixed incorrectly labeled namespace variables in twisted client. (Robert Booth)
  • Fixed that WBEMConnection.last_raw_reply was not set to the current reply in case of parsing errors in the reply. (Andreas Maier)
  • Reintroduced Python 2.6 support in cim_http.HTTPSConnection.connect() that disappeared in early drafts of this version: (Andreas Maier)
    • Removed SSLTimeoutError from except list; being a subclass of SSLError, it is catched via SSLError.
    • Invoked socket.create_connection() without source_address, if running on Python 2.6.
  • Fixed bug where HTTP body was attempted ot be read when CIMError header is set, causing a hang. (Andreas Maier)
  • Added CIM-XML declaration support for alternative PyWBEM client based on twisted. (Andreas Maier)
  • Added support for Windows to wbemcli.py, by making dependency on HOME environment variable optional, and adding HOMEPATH environment variable. Also, cleaned up the global namespace of wbemcli.py and made it importable as a module. (Andreas Maier)
  • Fixed errors in generated MOF (e.g. in any tomof() methods): (Andreas Maier)
    • Missing backslash escaping within string literals for n, r, t, “.
    • Representation of REF types was incorrect.
    • ‘=’ in array-typed qualifier declarations was missing.
    • Fixed size indicator was missing in array elements.
    • Qualifiers of method parameters were missing.
  • Improvements in generated MOF: (Andreas Maier)
    • Changed order of qualifiers to be sorted by qualifier name.
    • Added empty line before each property and method in the class for better readability.
    • Method parameters are now placed on separate lines.
    • Moved generation of method qualifiers from class into method. This changes the behavior of CIMMethod.tomof() to now generate the method qualifiers.
  • Fixed error where invoking mof_compiler.py with a file based URL that did not start with ‘file:’ failed with an undefined variable url_ in cim_http.py. Issue #1 on GitHub. (Klaus Kaempf, Andreas Maier)
  • Fixed build error that raised a YaccError in mof_compiler.py: “Syntax error. Expected ‘:’”. Issue #2 on GitHub. (Andreas Maier)
  • Fixed issue where MOF compiler did not find include files with a path specified. Issue #4 on GitHub. (Karl Schopmeyer)
  • Added missing LocalOnly parameter to EnumerateInstances() of the wbemcli script. Issue #33 on GitHub. (Karl Schopmeyer)
  • Added workaround for Python 2.6 for Python issue 15881.
  • Removed the lex.py and yacc.py files from PyWBEM, and used them from the ply package, which is their real home. This fixes a number of issues because the latest version is now used. Issue #8 on GitHub.i (Karl Schopmeyer)
  • Fixed the issue that the LEX and YACC table modules were regenerated under certain conditions. Issue #55 on GitHub. (Karl Schopmeyer)
  • Fixed bugs in the mof_compiler script. (Karl Schopmeyer)
  • Fixed errors in the description of the qualifier operations in WBEMConnection. Issue #91 on GitHub. (Andreas Maier)

Testing

  • Added support for running the unit test cases without having to be in the testsuite directory. This was done by setting up the DTD_FILE path correctly for any XML tests. (Andreas Maier)
  • Improved the quality of assertion messages issued when testcases fail, to include context information and types. (Andreas Maier)
  • Added docstrings to test cases. (Andreas Maier)
  • Added testcases for CIMProperty.__init__() to be comprehensive. (Andreas Maier)
  • In XML validation tests, added the expected XML root element. (Andreas Maier)
  • Added a header to any error messages issued by xmllint. (Andreas Maier)
  • Fix: Merged stderr into stdout for the xmllint invocation, xmllint error messages go to stderr and had been dropped before. (Andreas Maier)
  • Fix: The “mkdir -p ..:” command in the comfychair testcase constructor created subdirectories named “-p” when running on Windows; replaced that command with os.makedirs(). (Andreas Maier)
  • Fix: Replaced the “rm -fr ...” command in the comfychair testcase constructor with shutil.rmtree(), in order to better run on Windows. (Andreas Maier)
  • Fix: In comfychair._enter_rundir(), moved registration of cleanup function _restore_directory() to the end, so cleanup happens only if no errors happened. (Andreas Maier)
  • Fixed a bug in pywbem/trunk/testsuite/test_tupleparse.py in function ParseCIMProperty.runtest(), where the use of real tab characters caused a few lines to be incorrectly indented, and as a result, ignored for the test. (Andreas Maier)
  • Improved Windows portability in testsuite: Moved from using the Unix-only functions posix.WIFSIGNALED() and posix.WEXITSTATUS() for testing the success of subprocess.wait(), to simply testing for 0. (Andreas Maier)
  • Added ability to invoke test_cim_operations.py with comfychair arguments, and added printing of exception information if an operation fails. (Andreas Maier)
  • Migrated from comfychair to py.test, standard Python unittest, and to tox. (Andreas Maier)
  • Added test_client.py with a few initial testcases. This is an end-to-end test concept that allows specifying test cases that cover the entire PyWBEM Client top to bottom. It mocks the socket layer and allows specifying the test cases in YAML, starting with input at the PyWBEM Client API (e.g. an operation and its parameters), the expected CIM-XML request at the socket payload level resulting from this input (the request is verified), the CIM-XML response that is to be generated, and finally an expected result at the PyWBEM Client API that is being verified. (Andreas Maier)
  • Added use of Travis CI test environment. Commits to GitHub now trigger test runs on the Travis CI. A badge on the GitHub README page shows the current test result of the master branch, and links to the Travis site for the test results of the branches of any pull requests. (Andreas Maier)
  • Added support for reporting test coverage, using the Python ‘coverage’ package. Coverage is reported on stdout as part of testing, e.g. with ‘make test’ for the current Python environment, or with ‘tox’ for all supported Python environments. (Andreas Maier)
  • Added multiple tests for client connection timeout. A mock test was added for both HTTP and HTTPs. However, this causes an error in python 2 with HTTPS so two new options were added to test_client.py. First, a new parameter ignore_python_version was added to the yaml to define a major version of python for which a particulare testcase would be ignored. Second a non-documente option was added to test_client.py to execute a single testcase if the name of that testcase is the only parameter on the test_client.py cmd line. Finally a whole new run_operationtimeout.py file was added to testsuite to throughly test for timeouts. This runs ONLY against particular versions of OpenPegasus because it required adding a new method to OpenPegasus. However, it established that the timeouts apparently now really do work in both python 2 and python 3 with both http and https. (see issue #363)

Clean Code

  • Removed dangerous default parameter {} from CIMProperty and CIMInstanceName, and replaced it with None. To support that, added support for initializing an empty NocaseDict object from None. (Andreas Maier)
  • In cim_obj, changed the use of the deprecated backticks to using %r in the format string (which produces the same result). (Andreas Maier)
  • In the constructor of CIMInstanceName, added assertions to some paths that cannot possibly be taken based on the fact that the keybindings attribute is always a NocaseDict. They should be removed at some point. (Andreas Maier)
  • Addressed PyLint issues: (Andreas Maier, Karl Schopmeyer)
    • Consolidated imports at the top of the module (after module docstring), consistent with the PEP-8 recommendation.
    • Ensured order of imports: standard, non-standard, pywbem, local (on a subset of modules only).
    • Replaced wildcard imports with specific imports, as much as possible.
    • Removed unused imports.
    • Addressed PyLint issues that are related to whitespace, continuation indentation, and line length.
    • Replaced all real tab characters with spaces.
    • Many more PyLint issues

Packaging / Build

  • Fixed grammatical funkiness in the license text. No change to actual license - still LGPLv2. (Tim Potter)
  • Added LICENSE.txt file to release. (Tim Potter)
  • Added LICENSE.txt, NEWS, README and INSTALL files to distribution archive. (Andreas Maier)
  • Fixed inconsistencies in license text in file headers to consistently say LGPL 2.1 or higher (The LICENSE.txt file has always been LGPL 2.1). (Andreas Maier)
  • Removed confusing section about build from INSTALL file, to scope it just to the topic of installation. (Andreas Maier)
  • Restructured pywbem/trunk subtree to move pywbem package files into a pywbem subdirectory. (Andreas Maier)
  • Added a makefile (invoke ‘make help’ for valid targets). (Andreas Maier)
  • Added support for checking the Python source code using PyLint. (Andreas Maier)
  • Added support for generating HTML documentation using epydoc, and included the documentation into the distribution archive. The syntax used in Python docstrings is reStructuredText markdown. (Andreas Maier)
  • Added support for installing OS-level prerequisites via the new setup.py script commands ‘install_os’ and ‘develop_os’. (Andreas Maier)
  • Added support for installing Python-level prerequisites when installing in development mode using the setup.py script command ‘develop’. (Andreas Maier)

pywbem v0.7.0

Released: 2008-12-12

Bug Fixes

  • Fixed enumInstances and references in cim_provider to do a deep copy of the model before filtering instances so provider writers are less surprised. (Bart Whiteley)
  • Added CIMDateTime.__cmp__() so that CIMDateTime instances can be compared. (Bart Whiteley)
  • Fixed data types of method return values for python providers. (Bart Whiteley)
  • Fixed REF array out parameters in tupleparse.py. (Bart Whiteley)
  • Fixed Array parameters with no elements. (Bart Whiteley)
  • Fixed precision for real32 and real64 types. (Bart Whiteley)
  • Fixed Array properties where is_array isn’t set in __init__. (Bart Whiteley)
  • Added NocaseDict.__cmp__(self, other). (Bart Whiteley)
  • Fixed WBEMConnection.__repr__ for anonymous connections. (Tim Potter)
  • Fixed XML encoding of CIMQualifierDeclarations. (Bart Whiteley)
  • Fixed EnumerateQualifiers if there are no qualifiers. (Bart Whiteley)
  • Fixed InvokeMethod to only send a LOCALCLASSPATH or LOCALINSTANCEPATH, not a CLASSPATH or INSTANCEPATH. (Bart Whiteley)
  • Fix unexpected line break in basic auth header for long credentials. (Daniel Hiltgen)
  • Fix Host: HTTP header when connecting to a unix domain socket. (Bart Whiteley)
  • Fix deprecation warnings with Python 2.6. (Bart Whiteley)

Enhancements

  • Added support for generating Pegasus provider registration MOF in cim_provider.codegen(). (Bart Whiteley)
  • Implemented methods to parse indication export requests. (Bart Whiteley)
  • Python provider code generation enhancements. (Bart Whiteley)
  • Support for Pegasus Local authentication. (Bart Whiteley)
  • Support for Pegasus and OpenWBEM Unix Domain Socket. (Tim and Bart)
  • Added support for Pegasus non-compliant EMBEDDEDOBJECT XML attribute. (Bart Whiteley)
  • Added CIMQualifierDeclaration.tomof(). (Bart Whiteley)
  • Added a powerful MOF compiler. (Bart Whiteley)
  • Added property filtering to CIMInstance. (Bart Whiteley)
  • Added value attribute to CIMParameter. (Bart Whiteley)
  • Rigged CIMInstance to automagically update CIMInstance.path.keybindings as key properties are set. (Bart Whiteley)
  • Added cim_provider2.py: A new provider interface. Python providers using this interface can use the cmpi-bindings project within OMC (http://omc-project.org/) to run under any CIMOM supporting the CMPI interface. This is prefered to the old cim_provider.py interface that was used with the Python Provider Managers for OpenWBEM and Pegasus.
  • Changed __init__.py to not import anything from cim_provider.py (or cim_provider2.py) into the pywbem namespace. Existing providers based on cim_provider.py can still work with a minor adjustment involving importing CIMProvider from pywbem.cim_provider. The codegen funtion can now be obtained with from pywbem.cim_provider import codegen, or from pywbem.cim_provider2 import codegen or similar.
  • Added wbemcli.py command line utility. (Tim Potter)
  • Pass keyword args in unix domain socket connection functions down to WBEMConnection(). (Tim Potter)

pywbem v0.6

Released: 2007-10-26

Licensing

  • Relicensed from the GNU GPLv2 to the GNU LGPLv2.

API Changes

  • Add a type keyword arg and attribute to CIMQualifier, similar to the CIMProperty object, to allow the creation of null qualifiers. (Tim Potter)
  • Remove the toxml() method from CIM object classes. Use tocimxml().toxml() instead which specifies the CIM-XML representation of the object. (Tim Potter)
  • CIMDateTime class should now be used instead of datetime.datetime and datetime.timedelta.
  • Added a new method, CIMInstance.update_existing(). This behaves like update() on a dict, but only assigns new values to existing properties. It skips values for properties not already present in the instance. This is useful for honoring PropertyList within python providers.

Bug Fixes

  • Explicitly specify charset=”utf-8” in HTTP Content-type header as this is required now by the Pegasus cimserver. (Tim Potter)
  • Parse VALUETYPE elements that contain a TYPE attribute. This feature was introduced in version 2.2 of the CIM-XML DTD and produced by some CIMOMs such as the Java WBEM Server. (Tim Potter)
  • Don’t require CreateInstance to have the path attribute set but if it is, use the namespace from it. (Tim Potter)
  • Allow extrinsic methods to return object references. (Tim Potter)
  • Fix CIMInstanceName to support more numeric types of keybindings. (Bart Whiteley)
  • Fix datetime values to support utc offset. (Bart Whiteley)
  • Fix http client to monitor the connection more closely (RFC 2616 section 8.2.2). Previously, a large request could cause a socket exception with no ability to read the response and respond to an authentication challenge.
  • Fix NULL qualifiers to have a (required) type. (Martin Mrazik)
  • Fix initialising CIMInstanceName keys from a NocaseDict. (Bart Whiteley)
  • Return correct namespace in path for return value from GetInstance. (Tim Potter)
  • Numerous bugfixes to Twisted Python client. (Tim Potter)
  • Fix for x.509 SSL certificate handling. (Bas ten Berge)
  • EnumerateClassNames() now returns an empty list instead of None if there are no classes. (Bart Whiteley)

Enhancements

  • Support for OpenWBEM password-less local authentication. (Bart Whiteley)
  • Support for embedded objects is described in DSP0201-2.2.0 (Bart Whiteley)
  • New CIMDateTime class to deal with CIM-isms of datetimes. Most notably, datetime deals with timezone info poorly. (Bart Whiteley)
  • Add InvokeMethod() support in Twisted Python client. (Tim Potter)

pywbem v0.5

Released: 2006-11-21

API Changes

  • Many API changes were made to simplify the function and object interface of PyWBEM. Aspects of just about every CIM operation call and CIM object have changed. The major changes are:
    • The “LocalNamespacePath” keyword argument has been renamed to simply “namespace” for all CIM operations.
    • Replaced all object location classes with CIMInstanceName, and all instance classes with CIMInstance. CIMInstanceName now has “host” and “namespace” attributes to fully name a reference to an instance. The CIMInstance class now has a “path” attribute which is of type CIMInstanceName.
    • EnumerateInstances() now returns a list of CIMInstance objects (with path attribute set) instead of a list of CIMNamedInstance or tuples of (CIMInstanceName, CIMInstance).
    • All representations of properties can now be represented with the CIMProperty class.
  • All classes now have a copy() method which return a deep copy of the object. PyWBEM makes extensive use of dictionary objects which are passed by reference in Python. Use the copy() method to create and manipulate objects without modifying them by accident.

Bug Fixes

  • Fix parse bug when a CIMInstanceName is passed as the localobject parameter to WBEMConnection.InvokeMethod().
  • Fix parsing of INSTANCE elements containing PROPERTY.REFERENCE elements bug found by Bart Whiteley. This turns up when processing associations. (Tim Potter)
  • Handle extrinsic method calls that don’t return a value or any output parameters. (Tim Potter)
  • Fixed parsing of PARAMETER.ARRAY and PARAMETER.REFARRAY to not require optional attrs. (Bart Whiteley)
  • Atomic_to_cim_xml string generation for a datetime - was missing a >> ‘.’ in the string. (Norm Paxton)
  • InvokeMethod did not provide for None in output parameters. (Norm Paxton)

Enhancements

  • More parts of the class provider interface have been implemented. (Tim Potter, Bart Whiteley)
  • Many case-sensitivity bugs, mostly in __cmp__ methods, were found and fixed. (Tim Potter)
  • Implemented a test suite for maintaining backward compatibility and testing new features. (Tim Potter)
  • Implemented ExecQuery. (Bart Whiteley)
  • Allow a string classname to be passed as the localobject parameter to WBEMConnection.InvokeMethod(). (Tim Potter)
  • Add missing qualifiers on array properties. (Bart Whiteley)
  • Added code for performing asynchronous WBEM client operations using the Twisted Python framework. (Tim Potter)
  • Allow extrinsic method calls that take parameters. (Tim Potter)
  • Added cim_http.AuthError exception class. This is raised if the CIMOM returns a 401 (Unauthorized). Now the client can distinguish this condition, and (re)prompt for credentials. (Bart Whiteley)
  • Created cim_obj.CIMParameter class. Added return type, class origin, propagated to CIMMethod. CIMParameter object now allows parameter types and qualifiers to be obtained. (Bart Whiteley)
  • Implemented case-insensitive keys for property and qualifier dictionaries, as per the CIM specification. (Tim Potter, Bart Whitely)

pywbem v0.4

Released: 2005-11-15

Bug Fixes

  • Correctly calculate value of Content-Length HTTP header to include opening XML stanza. (Szalai Ferenc)
  • Fix syntax error when re-raising socket errors. (Pat Knight)

Enhancements

  • Support for marshaling and unmarshaling CIM dates object into Python datetime objects. (Szalai Ferenc)
  • Experimental module for making asynchronous WBEM calls with PyWBEM in Twisted Python. (Tim Potter)
  • Add parameter type checking for object location classes. (Tim Potter)
  • Allow caller to pass in a dictionary containing the location of the SSL certificate and key files as per the httplib.HTTPSConnection() class constructor. (Pat Knight)

API Changes

  • Change association provider API functions to take a fixed parameter for the named object instead of a keyword argument. This breaks backward compatibility. (Tim Potter)
  • Remove the CIMLocalNamespacePath class and replaced by a Python string. (Tim Potter)

Portability

  • Don’t use UserDict.DictMixin base class as it only exists in Python 2.3 and higher. (Tim Potter)

Tests

  • Add tests for parameter type checking for object location classes. (Tim Potter)
  • Add tests for string representation of object location classes. (Tim Potter)