Pywbem is a python implementation of the APIs defined by the DTMF WBEM Standards specifications.
pywbem Python API definitions
Examples of the use of these Python APIs.
..index:: single; examples Examples of the APIs are contained throughout this document (see examples in the document index), in a set of Jupyter notebooks Tutorial, and in the: pywbem repository examples directory (``pywbem/examples`) at <https://github.com/pywbem/pywbem/tree/master/examples/>`_ that is available in the pywbem github project and available when pywbem is cloned.
The major components of pywbem are shown in this diagram:
The green components all have Python APIs for use by user applications. The yellow components are command line utilities. The blue components are not part of the pywbem or pywbemtools packages.
The pywbem components all run on the client side and communicate with a remote WBEM server using the standard CIM operations over HTTP (CIM-XML) protocol defined in the DMTF standards DSP0200 and DSP0201.
Pywbem provides the following Python APIs:
WBEM server library - An API that encapsulates selected functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace and other basic information about the server, or the management profiles advertised by the server.
WBEM indication listener - An API for creating and managing a thread-based WBEM listener that waits for indications (i.e. event notifications) emitted by a WBEM server using the CIM-XML protocol. The API supports registering callback functions that get called when indications are received by the listener.
WBEM subscription manager - An API for viewing and managing subscriptions for indications on a WBEM server.
MOF compiler - An API for compiling MOF files or strings into a CIM repository (e.g. on a WBEM server), or for test-compiling MOF.
Mock WBEM server - An API for setting up a mocked WBEM server that is used instead of a real WBEM server. This allows setting up well-defined WBEM servers locally that can be used for example for prototyping or testing user applications.
Pywbem also provides a command line utility:
The related pywbemtools project provides the following command line utilities:
Pywbem is supported in these environments:
Operating Systems: Linux, OS-X, native Windows, UNIX-like environments under Windows (such as CygWin, MSYS2, Babun, or Gow).
Python: 2.7 (deprecated), 3.5, and higher
WBEM servers: Any WBEM server that conforms to the DMTF specifications listed in Standards conformance. WBEM servers supporting older versions of these standards are also supported, but may have limitations. See WBEM servers for more details.
Pywbem is a pure Python package and therefore does not have a dependency on operating system packages in addition to Python itself.
The Python environment into which you want to install must be the current Python environment, and must have at least the following Python packages installed:
Install pywbem (and its prerequisite Python packages) into the active Python environment:
$ pip install pywbem
This will also install any prerequisite Python packages.
Starting with version 1.0.0, pywbem has no OS-level prerequisite packages.
Note that installing with
setup.py install has been deprecated by
setuptools, as explained in
Why you shouldn’t invoke setup.py directly.
setup.py install is no longer supported by this package.
If you want to contribute to the pywbem project, you need to set up a development and test environment for pywbem. That has a larger set of Python package prerequisites and also OS-level prerequisites. Its setup is described in chapter Development.
1.3.1. Installing into a different Python environment
The examples in the previous sections install pywbem and its prerequisite Python packages using the Pip utility. By default, Pip installs these packages into the currently active Python environment. That can be the system Python, or a virtual Python. The commands shown above did not detail this, but this section does.
If you just want to use the scripts that come with pywbem, and want them to be always available without having to think about activating virtual Python environments, then installation of pywbem into the system Python environment is probably the right choice for you. If your intention is to write code against the pywbem APIs, installation into a virtual Python environment is recommended.
An additional dimension is Python 2 vs. Python 3:
On systems where Python 2 is the default, the
pipcommands operate on Python 2. There may be
pip3commands that operate on Python 3.
On some newer systems (e.g. Ubuntu 17.04), Python 3 is the default. In that case, the
pipcommands operate on Python 3. There may be
pip2commands that operate on Python 2.
For simplicity, the following examples show only the default commands.
To install pywbem into the currently active virtual Python environment (e.g.
(myenv)$ pip install pywbem
To install pywbem for only the current user into the currently active system Python environment, issue:
$ pip install --user pywbem
This installs the Python packages in a directory under the home directory of the current user and therefore does not require sudo permissions nor does it modify the system Python environment seen by other users.
To install pywbem for all users into the currently active system Python environment, issue:
$ sudo pip install pywbem
This installs the Python packages into a directory of the system Python installation and therefore requires sudo permissions.
Be aware that this may replace the content of existing packages when a package version is updated. Such updated packages as well as any newly installed packages are not known by your operating system installer, so the knowledge of your operating system installer is now out of sync with the actual set of packages in the system Python.
Therefore, this approach is not recommended and you should apply this approach only after you have thought about how you would maintain these Python packages in the future.
1.3.2. Installing a different version of pywbem
The examples in the previous sections install the latest version of pywbem that is released on PyPI. This section describes how different versions of pywbem can be installed.
To install the latest version of pywbem that is released on PyPI, issue:
$ pip install pywbem
To install an older released version of pywbem, Pip supports specifying a version requirement. The following example installs pywbem version 0.10.0 from PyPI:
$ pip install pywbem==0.10.0
If you need to get a certain new functionality or a new fix of pywbem that is not yet part of a version released to PyPI, Pip supports installation from a Git repository. The following example installs pywbem from the current code level in the master branch of the pywbem Git repository:
$ pip install git+https://github.com/pywbem/pywbem.git@master#egg=pywbem
1.3.3. Building a compiled archive with Cython
The ‘Cython’ package allows building a wheel distribution archive containing compiled code for Python packages such as pywbem. These distribution archives are nicknamed “cythonized” wheel distribution archives. They have the wheel format, but are specific to a Python version and to the target operating system.
Since the code in a cythonized wheel archive is native machine code for the target system, this speeds up execution in compute-intensive areas of pywbem such as when parsing the CIM-XML responses of a WBEM server. The downside is that a cythonized wheel archive is significantly larger than a universal wheel archive, and the memory consumption is also larger.
The pywbem project does not provide cythonized wheel distribution archives, but allows users to build them on their own. The build process for them is part of the regular tests to ensure they can be built.
To build the cythonized wheel distribution archive of pywbem, execute:
$ make buildc
The resulting distribution archive can be installed with Pip, for example:
$ pip install dist/pywbem-1.2.0.dev1-cp38-cp38-macosx_10_15_x86_64.whl
Pip will verify that the target system and Python version matches what the wheel archive was built for.
1.3.4. Verifying the installation
You can verify that pywbem is installed correctly by importing the package into Python (using the Python environment you installed pywbem to):
$ python -c "import pywbem; print('ok')" ok
In case of trouble with the installation, see the Troubleshooting section.
1.3.5. Prerequisite operating system packages for install
The installation of pywbem before its version 1.0.0 required certain operating system packages. Starting with version 1.0.0, pywbem has no dependencies on specific operating system packages (other than Python).
Note that the development of pywbem still requires a number of operating system packages. See Setting up the development environment for details.
Starting with pywbem 0.8.1, the version of the pywbem package can be accessed by
programs using the
- pywbem._version.__version__ = '1.7.0.dev1'
The full version of this package including any development levels, as a string.
Possible formats for this version string are:
“M.N.P.devD”: Development level D of a not yet released version M.N.P
“M.N.P”: A released version M.N.P
Note: For tooling reasons, the variable is shown as
pywbem._version.__version__, but it should be used as
Versions of pywbem that do not have the
pywbem.__version__ variable are
most likely version 0.7.0 because that was the only version before pywbem 0.8.1
that was released to Pypi, and most likely also the only version before
pywbem 0.8.1 that was packaged as an operating system package into Linux
The following shell command can be used to determine the version of a pywbem package installed in the current Python environment, for all versions that were released to Pypi, and independently of whether pywbem was installed as an operating system package or as a Python package:
python -c "import pywbem; print(getattr(pywbem, '__version__', None) or '0.7.0')"
Pywbem indicates support for version dependent features to users of its API.
These are features that have been introduced at some point, and users may have a need to depend on the feature being supported (i.e. active). If a feature is supported, the corresponding attribute is True. Note that before a feature was introduced, the corresponding attribute is undefined.
The attributes listed here do not allow controlling whether a feature is active or not; they only indicate whether the feature is supported and active.
Note: For tooling reasons, these attributes are shown as
pywbem._features.XXX, but they should be used as
The pywbem client and pywbem indication listener conform to the following CIM and WBEM standards, in the version specified when following the links to the standards:
The mock support of pywbem (see Mock WBEM server) does not support the
ModifyClassoperation. Note that in its implementation of the CIM-XML protocol, pywbem does support the
EnumerationCountoperation is not supported by pywbem. That operation is optional for WBEM servers to support, and is hard to implement reasonably.
Multi-requests are not supported by pywbem. This is not a functional limitation though, because the use of multi-requests is entirely determined by the client: If a client does not use multi-requests, the server does not use multi-responses.
DSP0201 version 2.4 introduced the requirement that the TYPE attribute of the KEYVALUE element must be set. The KEYVALUE element is used to represent keys in instance names, for example when the CreateInstance operation returns an instance name from the WBEM server, or when the DeleteInstance operation sends an instance name to the WBEM server. In operation requests sent to the WBEM server, pywbem sets the TYPE attribute of the KEYVALUE element for key properties of CIM types string and boolean, as required by DSP0201 version 2.4. For key properties with numeric CIM types, pywbem does not set the TYPE attribute of the KEYVALUE element in operation requests. This conforms to DSP0201 before version 2.4, but not to version 2.4. This is not expected to cause problems however, because WBEM servers that implement DSP0201 version 2.4 very likely will tolerate clients that conform to earlier versions. In operation responses received from the WBEM server, pywbem tolerates an absent TYPE attribute in KEYVALUE elements in order to accomodate WBEM servers that implement DSP0201 before version 2.4.
CORRELATORelement introduced in DSP0201 version 2.4 is not supported by pywbem.
The pywbem MOF compiler does not support the “EmbeddedObject” qualifier with a class definition.
The pywbem MOF compiler has the restriction that CIM instances specified in MOF that have an alias must have key properties that are either initialized in the instance, or have non-NULL default values (issue #1079).
The pywbem MOF compiler has the restriction that an alias must be defined before it is used. In the MOF syntax defined in DSP0004, no such restriction exists (issue #1078).
The pywbem MOF compiler does not roll back changes to qualifier declarations when it aborts (issue #990).
Note that the
__str__()methods of these two classes produce strings that are similar but not conformant to DSP0207, for historical reasons.
The mechanisms for discovering the Interop namespace of a WBEM server and the management profiles advertised by a WBEM server and their central instances in the WBEM server library conform to DSP1033.
Starting with version 0.7.0, pywbem attempts to be as backwards compatible as possible.
Compatibility of pywbem is always seen from the perspective of the user of the pywbem APIs or pywbem utility commands. Thus, a backwards compatible new version of pywbem means that a user can safely upgrade to that new version without encountering compatibility issues for their code using the pywbem APIs or for their scripts using the pywbem utility commands.
Having said that, there is always the possibility that even a bug fix changes some behavior a user was dependent upon. Over time, the pywbem project has put automated regression testing in place that tests the behavior at the APIs, but such compatibility issues cannot be entirely excluded.
Pywbem uses the rules of Semantic Versioning 2.0.0 for compatibility between versions, and for deprecations. The public interface that is subject to the semantic versioning rules and specificically to its compatibility rules are the various pywbem APIs described in this documentation, and the command line interface of the pywbem utility commands.
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 immediately. The deprecated functionality is still supported at least throughout new minor or update releases within the same major release. Eventually, a new major release may break compatibility by removing deprecated functionality.
Any changes at the pywbem APIs or utility commands that do introduce incompatibilities as defined above, are described in the Change log.
Deprecation of functionality at the pywbem APIs or utility commands is communicated to the users in multiple ways:
It is described in the documentation of the API or utility command
It is mentioned in the change log.
It is raised at runtime by issuing Python warnings of type
DeprecationWarning(see the Python
Starting with 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:
By invoking Python with the environment variable:
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
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; no new functionality; backwards compatible.
New minor release (M.N.U -> M.N+1.0): New deprecations may be added; functionality may be extended; backwards compatible.
New major release (M.N.U -> M+1.0.0): Deprecated functionality may get removed; functionality may be extended or changed; backwards compatibility may be broken.
The external APIs of pywbem are defined by the symbols in the
pywbem_mock namespaces/packages and their public sub-modules.
Sub-modules that have a leading underscore in their name are private and should not be used by users. Their content may change at any time without prior warning.
This documentation describes only the external APIs of pywbem, and omits any internal symbols and any private sub-modules.
Pywbem supports a very limited number of configuration variables that influence certain specific behavior.
These configuration variables can be modified by the user directly after importing pywbem. For example:
import pywbem pywbem.config.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.
- pywbem.config.AUTO_GENERATE_SFCB_UEP_HEADER = True
Option that enables or disables the automatic creation of a special HTTP header field that the Small Footprint CIM Broker (SFCB) requires when invoking its special “UpdateExpiredPassword()” method. See https://sblim.sourceforge.net/wiki/index.php/SfcbExpiredPasswordUpdate for details.
True: (default): Automatic creation is enabled, and pywbem will create the HTTP header field
Pragma: UpdateExpiredPasswordin all CIM-XML requests that invoke a CIM method named “UpdateExpiredPassword()”.
False: Automatic creation is disabled.
New in pywbem 0.13.
- 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
IterEnumerateInstances(), this value will be used as the value for MaxObjectCount. Note that this does not necessarily optimize the performance of these operations.
New in pywbem 0.10 as experimental and finalized in 0.12.
- pywbem.config.ENFORCE_INTEGER_RANGE = True
True (default): Pywbem enforces the allowable value range; Assigning values out of range causes
ValueErrorto 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.
New in pywbem 0.9.
- pywbem.config.IGNORE_NULL_KEY_VALUE = False
Backward compatibility option that controls creating
CIMInstanceNameobjects with NULL values for keybindings.
DSP0004, section 7.9 specifically forbids key properties with values that are NULL but because pywbem has always allowed this, adding the code to disallow None as a keybinding value is an incompatible change.
True: Pywbem tolerates None as a value when keybindings are defined.
False (default): Pywbem raises ValueError when keybindings are created where any key will have the value None.
New in pywbem 0.12.
- pywbem.config.SEND_VALUE_NULL = True
Backwards compatibility option controlling the use of VALUE.NULL for representing NULL entries in array values in CIM-XML requests sent to WBEM servers.
DSP0201 requires the use of VALUE.NULL for representing NULL entries in array values since its version 2.2 (released 01/2007). Pywbem added support for using VALUE.NULL in CIM-XML requests in its version 0.12. In case a WBEM server has not implemented support for VALUE.NULL, this config option can be used to disable the use of VALUE.NULL as a means for backwards compatibility with such WBEM servers.
Note that the config option only influences the behavior of pywbem for using VALUE.NULL in CIM-XML requests sent to a WBEM server. Regardless of the config option, pywbem will always support VALUE.NULL in CIM-XML responses the pywbem client receives from a WBEM server, and in CIM-XML requests the pywbem listener receives from a WBEM server.
True (default): Pywbem uses VALUE.NULL in CIM-XML requests for representing NULL entries in array values.
False: Pywbem uses VALUE with an empty value in CIM-XML requests for representing NULL entries in array values.
New in pywbem 0.12.
1.10.1. Server-specific features
Pywbem supports the following features of some specific WBEM servers that are additions to the DMTF standards:
Pywbem supports the Interop namespace
root/PG_InterOpthat is specific to OpenPegasus. OpenPegasus also supports the standard Interop namespaces (
root/interop) but for backwards compatibility with earlier versions of OpenPegasus, pywbem supports this old Interop namespace, for example in its Interop namespace determination whose result is exposed in the
Pywbem supports the upper-case variant
EMBEDDEDOBJECTof the respective CIM-XML attribute that is specific to some releases of OpenPegasus, in addition to the mixed-case variant
EmbeddedObjectthat is defined in the DSP0201 standard and that is also supported by OpenPegasus. Older releases of OpenPegasus supported only the upper-case variant.
Starting with version 1.0.0, pywbem no longer supports the Local authentication scheme of OpenPegasus, which is a password-less local authorization.
Starting with version 1.0.0, pywbem no longer supports the OWLocal authentication scheme of OpenWBEM, which is a password-less local authorization.
1.10.2. WBEM server testing
Today the pywbem project tests primarily against current versions of the OpenPegasus WBEM server because that server is available to the project.
These tests are captured in test scripts such as
tests/manualtest/run_cimoperations.py. Note that
generally those tests that are server-specific only run against the defined
server so that there are a number of tests that run only against the
OpenPegasus server. This includes some tests that use specific providers
in the OpenPegasus server to set up tests such as indication tests.
In addition, pywbem has automated testcases for testing against its own mock WBEM server, and against simulated CIM-XML responses.