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: https://pywbem.github.io/pywbem/index.html.
Introduction¶
Chapter Contents
Functionality¶
Pywbem supports the following functionality:
-
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.
-
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.
-
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.
-
This API provides for invoking the MOF compiler and for plugging in your own CIM repository into the MOF compiler.
-
Pywbem includes a few utility commands:
-
A MOF compiler that takes MOF files as input and updates the CIM repository of a WBEM server with the result. See DSP0004 for a definition of MOF.
-
A WBEM client in the form of a shell that provides an interactive Python environment for issuing WBEM operations to a WBEM server.
-
Installation¶
Pywbem is a pure Python package and therefore does not have a dependency on operating system packages in addition to Python itself. However, some of the Python packages used by pywbem have dependencies on additional operating system packages for their installation. Also, on some platforms, manual post-processing steps are needed, such as setting up environment variables.
This section describes the complete installation of pywbem with all steps including prerequisite operating system packages and manual post-processing steps, for users of pywbem. As a user of pywbem, you can import the pywbem Python package into your programs, and/or you can run the WBEM utility commands that come with pywbem.
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 OS-level prerequisites and its setup is described in chapter Development.
A note on the pywbem_os_setup.sh
script that is used for installation on
some platforms: That script installs the Python distro
package into the
active Python environment. If your active Python environment is a virtual
Python environment, that package will obviously be installed into that virtual
environment. If your active Python environment is the system Python
environment, that package will be installed into the system Python, but as a
local package for the current user. So it is not visible in the system Python
of other users, but still visible in the system Python of the current user.
This is done in order not to pollute the system Python installation with
additional Python packages that are not known at the OS-level package manager
(e.g. yum
on RedHat) and thus may be considered a maintenance problem.
Supported environments¶
Pywbem is supported in these environments:
- Operating Systems: Linux, Windows (native, and with UNIX-like environments), OS-X
- Python: 2.6, 2.7, 3.4, 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.
Limitations:
- On Windows (native), pywbem is not supported on Python 2.6, because the M2Crypto package does not support Python 2.6.
Announcement of removal of Python 2.6 support:
- The Python Software Foundation has stopped supporting Python 2.6 with the 2.6.9 release in october 2013. Since then, many Python package projects have continued releasing versions for Python 2.6, and so has pywbem. In 2017 and 2018, a number of Python package projects have actively removed support for Python 2.6 and it has become an increasingly difficult task for pywbem to keep supporting Python 2.6. For this reason, Python 2.6 support will be removed from pywbem in its future 1.0.0 version.
Installing to Linux¶
Prerequisites:
- 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:
- setuptools
- wheel (<0.30.0 on Python 2.6)
- pip
- 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:
Download the
pywbem_os_setup.sh
script from one of these sources:pywbem_os_setup.sh
- this version of the script fits exactly to the pywbem version of this documentation. However, its URL contains a UUID generated by the RTD site, so the URL is not predictable for future pywbem versions and can break tools that automate the installation process.- pywbem_os_setup.sh - this version of the script is the latest development level (i.e. the master branch of the pywbem Git repository). Its URL remains the same in the future, so this URL can be used for automated downloads of the script. Because the script is not expected to change much, this version should work also for older versions of pywbem.
That script installs OS-level prerequisite packages needed by pywbem.
Execute the
pywbem_os_setup.sh
script:$ ./pywbem_os_setup.sh
The script uses
sudo
under the covers to invoke the OS-level package manager for your Linux distribution (e.g.yum
on the RedHat family), so the current userid needs to have sudo permission.On older Linux versions, the Swig utility may not be available in the required version. In that case, the
pywbem_os_setup.sh
script will report that as an issue and one option on how to proceed is to build Swig yourself as described in Building Swig, and then to repeat execution of thepywbem_os_setup.sh
script.In case the script reports that your Linux distribution is not supported by the script, you can still try to find out what the corresponding OS-level packages are on your Linux distribution and install them manually. The script will list the names and versions of the OS-level packages for RedHat in that case, and you would need to find out what the corresponding packages are on your desired Linux distribution. If you were able to find these packages, please open an issue so we can add support for that Linux distribution to the script.
Only on Python 2.6 on Linux Debian family systems with multi-architecture support (e.g. Ubuntu 16.04 and higher):
Perform the following workaround to make the multi-architecture header files of OpenSSL available in a compatible way (the example is for x86_64 systems):
$ sudo ln -s /usr/include/x86_64-linux-gnu/openssl/opensslconf.h /usr/include/openssl/opensslconf.h
Background: One of the packages needed by pywbem on Python 2 is
M2Crypto
. During its own installation as a Python package,M2Crypto
needs the OpenSSL header files. On Linux Debian family systems with multi-architecture support, the structure of OpenSSL header files changed incompatibly (compared to earlier versions of these distributions). The installation ofM2Crypto
tries to accomodate that incompatibility by detecting multi-architecture support, but on Python 2.6 the interface for that was not yet supported. As a result, the OpenSSL header files are not found. The workaround established in this step makes the OpenSSL header files available in a compatible way, so that theM2Crypto
installation finds them.Install pywbem (and its prerequisite Python packages) into the active Python environment:
$ pip install pywbem
Installing to OS-X¶
Prerequisites:
- 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:
- setuptools
- wheel (<0.30.0 on Python 2.6)
- pip
- 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:
Download the
pywbem_os_setup.sh
script from one of these sources:pywbem_os_setup.sh
- this version of the script fits exactly to the pywbem version of this documentation. However, its URL contains a UUID generated by the RTD site, so the URL is not predictable for future pywbem versions and can break tools that automate the installation process.- pywbem_os_setup.sh - this version of the script is the latest development level (i.e. the master branch of the pywbem Git repository). Its URL remains the same in the future, so this URL can be used for automated downloads of the script. Because the script is not expected to change much, this version should work also for older versions of pywbem.
That script installs OS-level prerequisite packages needed by pywbem.
Execute the
pywbem_os_setup.sh
script:$ ./pywbem_os_setup.sh
The script uses
sudo
under the covers to invokebrew
(Homebrew project) to install OS-level packages, so the current userid needs to have sudo permission.Only on Python 2 on newer OS-X releases:
The
pywbem_os_setup.sh
script installs theopenssl
package needed by theM2Crypto
Python package. On newer OS-X releases, you may see a notice that theopenssl
package is “not linked” because the TLS implementation provided with OS-X is available. In that case, you need to set up the following environment variables for use by the pywbem package installation described in the next step:$ openssl_dir=$(brew --prefix openssl) $ export LDFLAGS="-L$openssl_dir/lib $LDFLAGS" $ export CFLAGS="-I$openssl_dir/include $CFLAGS" $ export SWIG_FEATURES="-I$openssl_dir/include $SWIG_FEATURES"
Install pywbem (and its prerequisite Python packages) into the active Python environment:
$ pip install pywbem
Installing to native Windows¶
This section describes the installation of pywbem into a native Windows environment. That is an environment where the Windows command processor is used to run any commands. Tools from UNIX-like environments may or may not be present in the PATH.
Prerequisites:
- The Python environment into which you want to install must be the active
Python environment, and must have at least the following Python packages
installed:
- setuptools
- wheel
- pip
- Windows command prompt in administrator mode.
- Chocolatey package manager installed (providing the
choco
command).
- The Python environment into which you want to install must be the active
Python environment, and must have at least the following Python packages
installed:
Download the
pywbem_os_setup.bat
script from one of these sources:pywbem_os_setup.bat
- this version of the script fits exactly to the pywbem version of this documentation. However, its URL contains a UUID generated by the RTD site, so the URL is not predictable for future pywbem versions and can break tools that automate the installation process.- pywbem_os_setup.bat - this version of the script is the latest development level (i.e. the master branch of the pywbem Git repository). Its URL remains the same in the future, so this URL can be used for automated downloads of the script. Because the script is not expected to change much, this version should work also for older versions of pywbem.
Execute the
pywbem_os_setup.bat
script:> pywbem_os_setup.bat
This script checks whether the following commands that are needed for installing and using pywbem are available in the PATH. If not, it installs them via
choco
:swig
curl
grep
chmod
tar
This script will also install the
M2Crypto
Python package into the active Python environment.This script will also download and install Win32 OpenSSL from https://slproweb.com/products/Win32OpenSSL.html.
Install pywbem (and its other prerequisite Python packages) into the active Python environment:
> pip install pywbem
Installing to a UNIX-like environment under Windows¶
This section describes the installation of pywbem into a UNIX-like environment
under Windows (such as CygWin, MSYS2, Babun, or Gow). That is an
environment where the UNIX/Linux shell of the UNIX-like environment (such as
bash
or sh
) is used to run any commands.
Note that Unix-like environments on Windows bring their own Python, so in such an environment, you install into that Python, and not into the Python of Windows.
Prerequisites:
- 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:
- setuptools
- wheel (<0.30.0 on Python 2.6)
- pip
- 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:
For CygWin, the
pywbem_os_setup.sh
script supports installation of the OS-level packages that are needed for using pywbem.Download the
pywbem_os_setup.sh
script from one of these sources:pywbem_os_setup.sh
- this version of the script fits exactly to the pywbem version of this documentation. However, its URL contains a UUID generated by the RTD site, so the URL not predictable for future pywbem versions and can break tools that automate the installation process.- pywbem_os_setup.sh - this version of the script is the latest development level (i.e. the master branch of the pywbem Git repository). Its URL remains the same in the future, so this URL can be used for automated downloads of the script. Because the script is not expected to change much, this version should work also for older versions of pywbem.
Execute the
pywbem_os_setup.sh
script:$ ./pywbem_os_setup.sh
For other UNIX-like environments under Windows, the prerequisite OS-level packages must be installed manually.
If you can help out here by providing the package names, please tell us by opening an issue).
Install pywbem (and its other prerequisite Python packages) into the active Python environment, by running in the UNIX/Linux shell of the UNIX-like environment:
$ pip install pywbem
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
python
andpip
commands operate on Python 2. There may bepython3
andpip3
commands that operate on Python 3. - On some newer systems (e.g. Ubuntu 17.04), Python 3 is the default. In that
case, the
python
andpip
commands operate on Python 3. There may bepython2
andpip2
commands 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
), issue:(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.
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
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.
Prerequisite operating system packages for install¶
The following table lists the prerequisite operating system packages along with their version requirements for installing and running pywbem, for the supported operating systems and Linux distributions. This list is for reference only, because the installation steps in the previous sections already take care of getting these packages installed.
The prerequisite operating system packages for developing pywbem are not listed in this table; you can find them in section Prerequisite operating system packages for development.
Op.system / Distribution | Package name | Version requirements | Notes |
---|---|---|---|
Linux RedHat family (RHEL, CentOS, Fedora) | openssl-devel | >=1.0.1 | py2 |
python-devel | for your Python 2.x | py2 | |
gcc-c++ | >=4.4 | py2 | |
swig | >=2.0 | py2 | |
Linux Debian family (Ubuntu, Debian, LinuxMint) | libssl-dev | >=1.0.1 | py2 |
python-dev | for your Python 2.x | py2 | |
g++ | >=4.4 | py2 | |
swig | >=2.0 | py2 | |
Linux SUSE family (SLES, openSUSE) | openssl-devel | >=1.0.1 | py2 |
python-devel | for your Python 2.x | py2 | |
gcc-c++ | >=4.4 | py2 | |
swig | >=2.0 | py2 | |
OS-X | openssl | >=1.0.1 | py2 |
gcc | >=4.4 | py2 | |
swig | >=2.0 | py2 | |
Windows (native) | None | ||
Windows (CygWin) | openssl | py2 | |
libssl-devel | py2 | ||
openssl-devel | py2 | ||
python2-devel | py2 | ||
python2-cython | py2 | ||
gcc | py2 | ||
swig | py2 |
Notes:
- py2: Only needed with Python 2 (not needed with Python 3).
Building Swig¶
The installation of M2Crypto needs the Swig utility (e.g. swig
package
on RedHat). On some Linux distributions, the Swig utility is not available in
the required version. In such cases, it can be built from its sources, as
follows:
Install the PCRE development packages:
pcre-devel
package on Linux RedHat and SUSE familieslibpcre3
andlibpcre3-dev
packages on Linux Debian family
Download the source archive of Swig version 2.0 or higher, and unpack it. For example, using Swig version 2.0.12:
$ wget -q -O swig-2.0.12.tar.gz https://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
Configure and build Swig:
$ cd swig-2.0.12 $ ./configure --prefix=/usr $ make swig
Install Swig (for all users of the system):
$ sudo make install
Verify the installation and the version of Swig:
$ swig -version SWIG Version 2.0.12
Package version¶
Since pywbem 0.8.1, the version of the pywbem package can be accessed by
programs using the pywbem.__version__
variable:
-
pywbem._version.
__version__
= '0.14.6'¶ The full version of this package including any development levels, as a string.
Possible formats for this version string are:
- “M.N.P.devNNN”: Development level NNN of a not yet released assumed M.N.P version
- “M.N.P”: A released M.N.P version
Note: For tooling reasons, the variable is shown as
pywbem._version.__version__
, but it should be used as
pywbem.__version__
.
From earlier versions of pywbem, pywbem 0.7.0 was the only version released to Pypi, and most likely also the only version that was packaged as an operating system package into Linux distributions.
The following shell command can be used to determine the version of pywbem, 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, os, subprocess; \
fs=os.path.join(os.path.dirname(pywbem.__file__),'setup.py'); \
vs=subprocess.check_output(['python',fs,'--version']).strip() \
if os.path.exists(fs) else None; \
v=getattr(pywbem, '__version__', vs if vs else '0.7.0-assumed'); \
print(v) \
"
Standards conformance¶
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 implementation of the CIM-XML protocol in pywbem (client and listener) conforms to DSP0200 and DSP0201.
Limitations:
- The mock support of pywbem (see Mock support) does not support the
ModifyClass
operation. Note that in its implementation of the CIM-XML protocol, pywbem does support theModifyClass
operation. - The
EnumerationCount
operation 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.
Notes:
- The CIM-XML representation as defined in DSP0201 supports CIM methods that have a void return type. However, the CIM architecture defined in DSP0004 does not support that, and neither does pywbem.
- The CIM-XML representation as defined in DSP0201 supports references to CIM classes. However, the CIM architecture defined in DSP0004 does not support that, and neither does pywbem.
- The mock support of pywbem (see Mock support) does not support the
The CIM-XML representation of CIM objects as produced by their
tocimxml()
andtocimxmlstr()
methods conforms to the representations for these objects as defined in DSP0201.Limitations:
- The xml:lang attribute supported by DSP0201 on some CIM-XML elements that can have string values is tolerated in the CIM-XML received by pywbem, but is ignored and is not represented on the corresponding CIM objects.
The capabilities of CIM objects conform to the CIM architecture as defined in DSP0004.
The MOF as produced by the
tomof()
methods on CIM objects and as parsed by the MOF compiler conforms to the MOF syntax as defined in DSP0004.Limitations:
- 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).
The WBEM URIs produced by the
to_wbem_uri()
methods ofCIMInstanceName
andCIMClassName
conform to the WBEM URI syntax as defined in DSP0207.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 API conform to DSP1033.
The mechanisms for subscribing for CIM indications in the WBEM indication API conform to DSP1054.
Deprecation and compatibility policy¶
Since 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 Pythonwarnings
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; 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.
Python namespaces¶
The external APIs of pywbem are defined by the symbols in the pywbem
namespace. 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.
With pywbem versions prior to v0.11, the MOF compiler API was only
available in the pywbem.mof_compiler
namespace. Starting with pywbem
version v0.11, it is also available in the pywbem
namespace and should be
used from there.
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 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.
ENFORCE_INTEGER_RANGE
= True¶ Enforce the allowable value range for CIM integer types (e.g.
Uint8
). For details, see theCIMInt
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.
New in pywbem 0.9.
- True (default): Pywbem enforces the allowable value range; Assigning
values out of range causes
-
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 asIterEnumerateInstances()
, 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.
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.
-
pywbem.config.
IGNORE_NULL_KEY_VALUE
= False¶ Backward compatibility option that controls creating
CIMInstanceName
objects 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.
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: UpdateExpiredPassword
in all CIM-XML requests that invoke a CIM method named “UpdateExpiredPassword()”. - False: Automatic creation is disabled.
New in pywbem 0.13.
- True: (default): Automatic creation is enabled, and pywbem will create
the HTTP header field
WBEM servers¶
Server-specific features¶
Pywbem supports the following features of some specific WBEM servers that are additions to the DMTF standards:
- OpenPegasus
- Pywbem supports the Interop namespace
root/PG_InterOp
that is specific to OpenPegasus. OpenPegasus also supports the standard Interop namespaces (interop
,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 thepywbem.WBEMServer.interop_ns
property. - Pywbem supports the upper-case variant
EMBEDDEDOBJECT
of the respective CIM-XML attribute that is specific to some releases of OpenPegasus, in addition to the mixed-case variantEmbeddedObject
that is defined in the DSP0201 standard and that is also supported by OpenPegasus. Older releases of OpenPegasus supported only the upper-case variant. - Pywbem supports a connection to an OpenPegasus server using Unix Domain
Sockets through its
PegasusUDSConnection
subclass ofWBEMConnection
.
- Pywbem supports the Interop namespace
- SFCB (Small Footprint CIM Broker)
- Pywbem supports a connection to an SFCB server using Unix Domain
Sockets through its
SFCBUDSConnection
subclass ofWBEMConnection
.
- Pywbem supports a connection to an SFCB server using Unix Domain
Sockets through its
- OpenWBEM
- Pywbem supports the OWlocal authentication extension of OpenWBEM, which is a password-less local authorization.
- Pywbem supports a connection to an OpenWBEM server using Unix Domain
Sockets through its
OpenWBEMUDSConnection
subclass ofWBEMConnection
.
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 the test script 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.
Concepts¶
This sections defines some of the basic concepts that form the basis for Pywbem including the architecture, basic CIM/WBEM components, operations and indications.
It also defines the differences between some of the methods defined in Pywbem cim_operations, in particular, the pull operations and the iter operations.
Chapter Contents
The CIM/WBEM architecture¶
TODO: Write this section
The CIM model and CIM objects¶
TODO: Write this section
WBEM Operations: Communicating with the WBEM Server¶
TODO: Write this section
WBEM operations overview¶
TODO Write this section
Traditional operations¶
TODO - Write this section
Pull operations¶
The DMTF CIM/XML pull operations allow the WBEM client to break the monolithic instance operations for requests that deliver multiple objects into multiple requests/responses executed as a sequence of requests to limit the size of individual responses.
NOTE: The pull operations were added to pywbem in version 0.9.0.
They were created to reduce scalability issues with extremely large responses from servers for instance enumerate operations (EnumerateInstances, Associators, and References) that were causing resource problems in both clients and servers. The pull operations allow the client to break large responses up into multiple smaller responses and allowing filtering of the responses to be performed by the server.
A central concept of pulled enumeration operations is the enumeration session, which provides a context in which the operations perform their work and which determines the set of instances or instance paths to be returned. To process the operations of an enumeration session, some parameters of the open operation need to be maintained as long as the enumeration session is open. In addition, some state data about where the enumeration session is with regard to instances or instance paths already returned must be maintained.
A successful Open… operation establishes the enumeration session and returns an enumeration context (Pybbem result.context) value representing that session. This value is used as a parameter in subsequent Pull operations on that enumeration session.
In general the pull operations replace the single monolithic request/response (ex. EnumerateInstances) that returns all instances in a single response with a pattern (enumeration sequence) that is based on three operations:
- Open… to open the request enumeration session to the WBEM Server and optionally request objects be returned.
- Pull… to continue retrieving objects from the WBEM Server after a successful Open…. The client normally continues to execute pulls until an exception or end-of-sequence flag is received.
- CloseEnumeration Close an enumeration sequence before it is complete. This request is ONLY used to execute early close; when the eos flag is returned or and error is returned (if ContinueOnError is not set), the session is closed by the server.
The open… requests use the same request parameters as the traditional operations to define the basic characteristics of the corresponding traditional operation (object name, propertylists, etc) and add several more request parameters to control the flow of responses (response size, timeouts, etc.). In addition they add two new request parameters (QueryFilter and QueryFilterLanguage) to request that the server filter the responses and return only instances/paths that match the filter.
Relation to traditional operations¶
The convention for the pull operation naming is as follows:
- Prepend the traditional operation name with Open and Pull
- Suffix the pull operations that return both instances and paths with WithPath
- Change the name suffix on operations that return path information from Names to Paths to reflect that these operations are returning complete instance paths with host and namespace included. The Exec was dropped from the name for the OpenQueryInstances.
The pull operations parallel to the traditional operations as follows:
Traditional Operation | Pull Operations |
EnumerateInstances | OpenEnumerateInstances / PullInstancesWithPath |
EnumerateInstanceNames | OpenEnumerateInstancePaths / PullInstancePaths |
Associators | OpenAssociatorInstances / PullInstancesWithPath |
AssociatorNames | OpenAssociatorInstancePaths / PullInstancePaths |
References | OpenReferenceInstances / PullInstancesWithPath |
ReferenceNames | OpenReferenceInstancePaths / PullInstancePaths |
ExecQuery | OpenQueryInstances / PullInstances |
The pull operations are defined only for instances. There are NO pull operations for CIM classes, the for CIM qualifier declarations or for method invocations.
Pull operation responses¶
Each pull operation request returns a Python namedtuple result that consists of the following named components:
- eos - A boolean flag that indicates the end of the enumeration sequence. As along as this returned flag is false, the server has more objects to return. If this flag is true in a response, the server has no more objects to return and it has closed the enumeration sequence.
- context - An opaque identifier that must be returned to the server with subsequent pull requests to continue the enumeration sequence. The context received with a response within an enumeration must be returned with the next request since the context may uniquely define not only the enumeration sequence but the segement returned in the response.
- instances or paths - A list of pywbem objects returned from the server. The requests that demand instances return the instances entry in the namedtuple and those that request paths return paths in the path entry in the namedtuple.
Pull enumeration sequence code pattern¶
Generally the pattern for requesting from a server using the pull operations is as follows:
# open the enumeration sequence
result = open...(uri, ...)
... process the objects return in result.xx
# while more objects exist in the server, loop to pull objects
while not result.eos
result = pull...(result.context, <MaxObjectCount>, ...)
... process the objects return in result.xx
The user opens the request with the open request and if that is successful, and does not return the end-of-sequence flag the result (eos) executed the pull request to continue receiving objects within the enumeration sequence. Each pull request MUST include the enumeration context from the previous response (context in the result tuple).
The pull sequence may be terminated by executing a [CloseEnumeration()](https://pywbem.readthedocs.io/en/latest/client.html#pyw bem.WBEMConnection.CloseEnumerate) to terminate the pull sequence. However, this is optional and used only to close pull sequences before the eos has been received.
Common Pull Operation Request Input Arguments¶
The following are the request arguments that are common across all of the Pull requests.
Open requests¶
- FilterQuery Language and FilterQuery - These input parameters specify a filter query that acts as an additional restricting filter on the set of enumerated instances/paths returned. WBEM servers must support filter queries in pulled enumerations and must support the DMTF Filter Query Language(FQL, see DMTF DSP0212) as a query language. If a WBEM server accepts a request with the FilterQuery parameter defined it MUST filter the response. NOTE: The query and query language defined for the OpenQueryInstances is NOT FQL but the same query languages defined for the execQuery request.
- OperationTimeout - Determines the minimum time the WBEM server shall maintain the opened enumeration session after the last Open or Pull operation (unless the enumeration session is closed during the last operation). If the operation timeout is exceeded, the WBEM server may close the enumeration session at any time, releasing any resources allocated to the enumeration session. An OperationTimeout of 0 means that there is no operation timeout. That is, the enumeration session is never closed based on time. If OperationTimeout is NULL, the WBEM server shall choose an operation timeout.
- ContinueOnError - This input parameter, if true, requests a continuation on error, which is the ability to resume an enumeration session successfully after a Pull operation returns an error. If a WBEM server does not support continuation on error and ContinueOnError is true, it shall return a failure with the status code CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED. Most servers today do not support ContinueOnError.
- MaxObjectCount - Defines the maximum number of instances or instance paths that the open operation can return. Any uint32 number is valid, including 0. The WBEM server may deliver any number of instances or instance paths up to MaxObjectCount but shall not deliver more than MaxObjectCount elements. The default for this is zero so that the WBEM server does not deliver objects in the response unless a MaxObjectCount is specifically defined. The WBEM server may limit the maximum size of this request parameter.
Pull requests¶
- Context - This is the EnumerationContext defined in the specification. It is an opaque string returned from the previous open or pull for this enumeration sequence as part of the result tuple (result.context).
- MaxObjectCount - This required input parameter defines the maximum number of instances or instance paths that may be returned by this Pull operation. Any uint32 number is valid, including 0. The WBEM server may deliver any number of instances or instance paths up to MaxObjectCount but shall not deliver more than MaxObjectCount. The WBEM client may use a MaxObjectCount value of 0 to restart the operation timeout for the enumeration session when it does not need to not retrieve any instances or instance paths.
Close request¶
- Context - This is the EnumerationContext defined in the specification. It is an opaque string returned from the previous open or pull for this enumeration sequence as part of the result tuple (result.context).
Differences from traditional operations¶
The pull operations differ from the traditional operations in the several ways:
- They allow filtering the response in the WBEM Server which can represent a significant resource saving if only selected instances from a large response are really required.
- They limit the amount of memory used by the server since the server need not process the complete request before returning information to the client
- They limit the memory used by the client since it can define the maximum size of any response.
- They allow the client to terminate an enumeration early with the CloseEnumeration.
- They allow the server and client to receive partial responses in that the client receives potentially an error response on each segment of the response, not the overall response.
- They provide a more consistent inclusion of the path component in the responses.
Iter operations¶
The iterable operation extensions (short: iter operations) are a set of methods added to [pywbem.WBEMConnection](https://pywbem.readthedocs.io/en/latest/client.html# pywbem.WBEMConnection) class in pywbem version 0.10.0 to simplify the use of the pull vs. traditional operations.
These are specific to PyWBEM.
Why the iter operations exist¶
The iter operations provide:
1. An interface that is the same whether the user is executing the pull operations or their equivalent traditional operations.
2. An interface that use the Python iterator paradigm to get instances or instance paths in place of lists or tuples as for the pull operations and traditional operations.
3. An interface that allows the user to utilize pull operations or traditional operations with just an attribute change in WBEMConnection.
4. An interface that automatically attempts to use pull operations and if a particular WBEM server does not support them falls back to the equivalent traditional operations so the user does not need to worry about whether the server supports the pull operations or if they are required for memory optimization.
Comparison table¶
The traditional operations and their equivalent pull operations are covered by the new iter operations as follows:
Traditional Operation | Pull Operations | Iter Operation |
EnumerateInstances | OpenEnumerateInstances / PullInstancesWithPath | IterEnumerateInstances |
EnumerateInstanceNames | OpenEnumerateInstancePaths / PullInstancePaths | IterEnumerateInstancePaths |
Associators | OpenAssociatorInstances / PullInstancesWithPath | IterAssociatorInstances |
AssociatorNames | OpenAssociatorInstancePaths / PullInstancePaths | IterAssociatorInstancePaths |
References | OpenReferenceInstances / PullInstancesWithPath | IterReferenceInstances |
ReferenceNames | OpenReferenceInstancePaths / PullInstancePaths | IterReferenceInstancePaths |
ExecQuery | OpenQueryInstances / PullInstances | IterQueryInstances |
The methods for the iter operations use the same arguments as the Open… methods of the pull operations, with exceptions noted in section :ref: Differences between iter operations and pull operations.
The general pattern for use of the iter operations is:
try:
iterator = Iter...(...)
for object in iterator:
<process the object>
except Error as er:
# NOTE: objects may be received before an exception, because in each call
# the server returns either objects or error. However, generally the
# first error terminates the whole sequence.
These operations use the Python iterator paradigm so that the for-loop processes CIM objects as they are received via the pull operations or via the traditional operations if the server does not support pull operations.
Internal processing in the iter operations¶
The iter operations try to use the existing pull operations or traditional operations and lay a layer over them to determine if the pull operations can be used and to manage the iteration. The paradigm for the implementation of each of these operations is generally as follows (showing an operation returning instances as an example, and omitting the logic that closes the pull operation):
# psuedo code pattern for iter function internal processing
if <use_pull_for_this_operation is try or true>:
try:
result = Open...(...)
<use_pull_for_this_operation = true>
for inst in result.instances:
yield inst
while not result.eos:
result = PullInstancesWithPath(...)
for inst in result.instances:
yield inst
return
except CIMError as ce:
if <use_pull_for_this_operation is try> and
ce.status_code != "CIM_ERR_NOT_SUPPORTED":
<use_pull_for_this_operation = false>
else:
raise
<check for unsupported parameters when using traditional operations>
instances = <traditional-operation>(...)
for inst in instances:
<fix up path in instance>
yield inst
Forcing pull vs. traditional operations¶
A parameter (use_pull_operations) has been added to the [pywbem.WBEMConnection](https://pywbem.readthedocs.io/en/latest/client.html# pywbem.WBEMConnection) constructor to optionally force the use of either the pull operations or the traditional operations.
- If use_pull_operations is True only the pull operations will be executed and if this fails for any reason including CIM_ERR_NOT_SUPPORTED, the exception will be returned.
- If use_pull_operations is False only the traditional operations will be executed and if this fails for any reason, the exception will be returned.
- The default is None. In this case, first the pull operation will be attempted. If the first request (Open…) returns CIM_ERR_NOT_SUPPORTED, the corresponding traditional operation will be attempted.
Thus, the iter operations can be used to execute exclusively the traditional operations by simply setting use_pull_operations=False.
conn = pywbem.WBEMConnection(server, (username, password),
default_namespace=namespace,
no_verification=True,
use_pull_operations=False)
.._Differences between iter operations and pull operations:
Differences between iter operations and pull operations¶
Use of FilterQuery¶
Since the traditional operations did not incorporate the query filters into their input parameters, if a query filter is included in the request and the request is passed to a traditional operation, the request will be refused and an exception generated. This is because the specification for the FilterQuery states that the server must return filtered responses and there is no way to do that with the traditional operations.
Paths in returned instances¶
The requirements on paths in returned instances differ between pull and traditional operations. The iter operations have been defined to be in line with the requirements on paths for pull operations, and the implementation of the iter operations acts to bring the path in returned instances in line with the requirements of the pull operations, if it uses the traditional operation. Thus, the iter operation always returns a complete path in any returned instances.
Use of MaxObjectCount argument¶
The MaxObjectCount argument is somewhat more limited than if the pull operations are used directly in that:
- It is the same value for open and pull requests.
- The mechanism to delay responses (setting MaxObjectCount=0 and executing a Pull…() method) cannot be used so the interoperation timeout must be sufficient for the client to complete its processing.
Receiving returned objects before an exception¶
In general the pull operations receive either objects or error for each request (open or pull). Since these operations may be called to get objects from the server the iterator may receive objects before an exception is executed. In general, unless the ContinueOnError flag is set, the enumeration sequence will terminate after the first error and that error is an indication that not all objects were received from the server. If the traditional enumerate function is called by the Iter…() method, either objects or an error are received, never both.
Closing an Iter operation before it is complete¶
An iter operation may be closed before the processing from the server is complete by executing the close() function on the iterator:
inst_iterator = conn.IterEnumerateInstances(classname,
MaxObjectCount=max_obj_cnt)
for inst in inst_iterator:
if <instance fails some test>
inst_iterator.close()
else:
<process the instance>
Note that if the operation executed was the traditional operation rather than the pull operation, the close() will do nothing since the response instances are received as a single block. If the enumeration sequence is already complete, this call will also be ignored.
WBEM indications and subscriptions¶
TODO: Section on indications and subscriptions
WBEM Management Profiles¶
TODO: Create this section describing profiles, why there exist and very generally how to use them
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.
Table of Jupyter tutorials¶
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 |
pulloperations.ipynb | The Pull Operations |
iterablecimoperations.ipynb | The Iterable Operation Extensions |
wbemserverclass.ipynb | Pywbem WBEMServer Class |
subscriptionmanager.ipynb | Subscription Manager |
pywbemmock.ipynb | Using the pywbem_mock module |
For the following topics, tutorials are not yet available:
- ExecQuery
- Association Operations
- Class Operations
- Qualifier Operations
- WBEMListener
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.
A number of these topics apply also to the other APIs of the pywbem package.
Chapter Contents
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 |
---|---|
EnumerateInstances() |
Enumerate the instances of a class (including instances of its subclasses) |
EnumerateInstanceNames() |
Enumerate the instance paths of 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 |
Associators() |
Retrieve the instances (or classes) associated to a source instance (or source class) |
AssociatorNames() |
Retrieve the instance paths of the instances (or classes) associated to a source instance (or source class) |
References() |
Retrieve the association instances (or association classes) that reference 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) |
InvokeMethod() |
Invoke a method on a target instance or on a target class |
ExecQuery() |
Execute a query in a namespace |
IterEnumerateInstances() |
Iterator API that uses either OpenEnumerateInstances and PullInstancesWithPath or EnumerateInstances depending on the attributes and existence of pull operations in the server. |
IterEnumerateInstancePaths() |
Iterator API that uses either OpenEnumerateInstances and PullInstancesWithPath or EnumerateInstances depending on the attributes and existence of pull operations in the server. |
IterAssociatorInstances() |
Iterator API that uses either OpenAssociatorInstances and PullInstancesWithPath or Associators depending on the attributes and existence of pull operations in the server. |
IterAssociatorInstancePaths() |
Iterator API that uses either OpenAssociatorInstances and PullInstancesWithPath or Associators depending on the attributes and existence of pull operations in the server. |
IterReferenceInstances() |
Iterator API that uses either OpenReferenceInstances and PullInstancesWithPath or References depending on the attributes and existence of pull operations in the server. |
IterReferenceInstancePaths() |
Iterator API that uses either OpenReferenceInstances and PullInstancesWithPath or References depending on the attributes and existence of pull operations in the server. |
IterQueryInstances() |
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) |
OpenEnumerateInstancePaths() |
Open enumeration session to retrieve instances of a class (including instances of its subclass) |
OpenAssociatorInstances() |
Open enumeration session to retrieve the instances associated to a source instance |
OpenAssociatorInstancePaths() |
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 |
OpenReferenceInstancePaths() |
Open enumeration session to retrieve the instances that reference a source instance |
OpenQueryInstances() |
Open query request to retrieve instances defined by the query parameter in a namespace |
PullInstancesWithPath() |
Continue enumeration session opened with OpenEnumerateInstances, OpenAssociatorInstances, or OpenReferenceinstances |
PullInstancePaths() |
Continue enumeration session opened with OpenEnumerateInstancePaths, OpenAssociatorInstancePaths, or OpenReferenceInstancePaths |
PullInstances() |
Continue enumeration of enumeration session opened with OpenExecQuery |
CloseEnumeration() |
Close an enumeration session in process. |
EnumerateClasses() |
Enumerate the subclasses of a class, or the top-level classes in a namespace |
EnumerateClassNames() |
Enumerate the names of subclasses of a class, or of 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 WBEM servers so was not implemented in pywbem.
WBEMConnection¶
-
class
pywbem.
WBEMConnection
(url, creds=None, default_namespace=None, x509=None, verify_callback=None, ca_certs=None, no_verification=False, timeout=None, use_pull_operations=False, stats_enabled=False)[source]¶ A client’s connection to a WBEM server. This is the main class of the WBEM client library API.
The connection object knows a default CIM namespace, which is used when no namespace is specified on subsequent WBEM operations (that support specifying namespaces). Thus, the connection object can be used as a connection to multiple CIM namespaces on a WBEM server (when the namespace is specified on subsequent operations), or as a connection to only the default namespace (this allows omitting the namespace on subsequent operations).
As usual in HTTP, there is no persistent TCP connection; the connectedness provided by this class is only conceptual. That is, the creation of the connection object does not cause any interaction with the WBEM server, and each subsequent WBEM operation performs an independent, state-less HTTP/HTTPS request.
After creating a
WBEMConnection
object, various methods may be called on the object, which cause WBEM operations to be issued to the WBEM server. See WBEM operations for a list of these methods.CIM elements such as instances or classes are represented as Python objects (see CIM objects). The caller does not need to know about the CIM-XML encoding of CIM elements and protocol payload that is used underneath (It should be possible to use a different WBEM protocol below this layer without disturbing any callers).
The connection remembers the XML of the last request and last reply if debugging is turned on via the
debug
attribute of the connection object. This may be useful in debugging: If a problem occurs, you can examine thelast_request
andlast_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 thelast_raw_request
andlast_raw_reply
attributes of the connection object.WBEMConnection objects can record the operations performed by calling
WBEMConnection
methods that interact with a WBEM server using operation recorders, at the level of method calls and returns, and at the level of CIM-XML requests and responses. TheLogOperationRecorder
class records the operations in the Python logging facility. This recorder is activated through the connection parameter ofconfigure_logger()
. TheTestClientRecorder
class records the operations in a file in the YAML format suitable for the test_client.py unit test program. Before version 0.11.0, pywbem supported only a single operation recorder and activating/deactivating the recorder was a simple matter of setting theoperation_recorder
attribute. Starting with pywbem version 0.11.0, pywbem added support for multiple operation recorders and deprecated theoperation_recorder
attribute. Theadd_operation_recorder()
method is now used to add an operation recorder to a connection, and theoperation_recorders
property is used to retrieve the current operation recorders of a connection.The methods of this class may raise the following exceptions:
Exceptions indicating operational errors:
ConnectionError
- A connection with the WBEM server could not be established or broke down.AuthError
- Authentication failed with the WBEM server.TimeoutError
- The WBEM server did not respond in time and the client timed out.
Such exceptions can typically be resolved by the client user or server admin.
Exceptions indicating server-side issues:
HTTPError
- HTTP error (bad status code) received from WBEM server.CIMXMLParseError
- The response from the WBEM server cannot be parsed because it is invalid CIM-XML (for example, a required attribute is missing on an XML element).XMLParseError
- The response from the WBEM server cannot be parsed because it is invalid XML (for example, invalid characters or UTF-8 sequences, or ill-formed XML).
Such exceptions nearly always indicate an issue with the implementation of the WBEM server.
Other exceptions:
CIMError
- The WBEM server returned an error response with a CIM status code.
Depending on the nature of the request, and on the CIM status code, the reason may be a client user error (e.g. incorrect class name) or a server side issue (e.g. some internal error in the server).
Exceptions indicating programming errors (in pywbem or by the user):
TypeError
KeyError
ValueError
AttributeError
- … possibly others …
Exceptions indicating programming errors should not happen. If you think the reason such an exception is raised lies in pywbem, report a bug.
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 authentication 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 anAuthorization
header using HTTP Basic Authentication.See Authentication types for an overview.
- default_namespace (string) –
Default CIM namespace for this connection.
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection will be set to the built-in default namespace
"root/cimv2"
.The default namespace of the connection is used if no namespace or a namespace of None is specified for an operation.
- 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:
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 https://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 must be one of:
- a path to a file containing one or more CA certificates in PEM format. See the description of CAfile in the OpenSSL SSL_CTX_load_verify_locations function for details.
- a path to a directory with files each of which contains one CA certificate in PEM format. See the description of CApath in the OpenSSL SSL_CTX_load_verify_locations function for details.
If None, the directory path of the first existing directory from the list in
DEFAULT_CA_CERT_PATHS
will be used as a default. - no_verification (
bool
) –Disables verification of the X.509 server certificate returned by the WBEM server during TLS/SSL handshake, disables verification of the hostname, and disables the invocation of a verification function specified in verify_callback.
If True, verification is disabled; otherwise, verification is enabled.
This parameter is ignored when HTTP is used.
Disabling the verification of the server certificate is insecure and should be avoided!
- timeout (number) –
Timeout in seconds, for requests sent to the server.
New in pywbem 0.8.
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.
New in pywbem 0.11 as experimental and finalized in 0.13.
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 from then on, on this connection. This detection is performed for each pull operation separately, in order to accomodate WBEM servers that support only some of the pull operations. This will work on any WBEM server whether it supports no, some, or all pull operations.
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 (default) means that the Iter…() methods will only use traditional operations.
- stats_enabled (
bool
) –Initial enablement status for maintaining statistics about the WBEM operations executed via this connection.
New in pywbem 0.11 as experimental, renamed from `enable_stats` and finalized in 0.12.
See the WBEM operation statistics section for details.
Methods
AssociatorNames
Retrieve the instance paths of the instances associated to a source instance, or the class paths of the classes associated to a source class. Associators
Retrieve the instances associated to a source instance, or the classes associated to a source class. CloseEnumeration
Close an open enumeration session, causing an early termination of an incomplete enumeration session. CreateClass
Create a class in a namespace. CreateInstance
Create an instance in a namespace. DeleteClass
Delete a class. DeleteInstance
Delete an instance. DeleteQualifier
Delete a qualifier type (= qualifier declaration). 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. EnumerateInstanceNames
Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace. EnumerateInstances
Enumerate the instances of a class (including instances of its subclasses) in a namespace. EnumerateQualifiers
Enumerate the qualifier types (= qualifier declarations) in a namespace. ExecQuery
Execute a query in a namespace. GetClass
Retrieve a class. GetInstance
Retrieve an instance. GetQualifier
Retrieve a qualifier type (= qualifier declaration). InvokeMethod
Invoke a method on a target instance or on a target class. IterAssociatorInstancePaths
Retrieve the instance paths of the instances associated to a source instance, using the Python generator idiom to return the result. IterAssociatorInstances
Retrieve the instances associated to a source instance, using the Python generator idiom to return the result. IterEnumerateInstancePaths
Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result. IterEnumerateInstances
Enumerate the instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result. IterQueryInstances
Execute a query in a namespace, using the Python generator idiom to return the result. IterReferenceInstancePaths
Retrieve the instance paths of the association instances that reference a source instance, using the Python generator idiom to return the result. IterReferenceInstances
Retrieve the association instances that reference a source instance, using the Python generator idiom to return the result. ModifyClass
Modify a class. ModifyInstance
Modify the property values of an instance. OpenAssociatorInstancePaths
Open an enumeration session to retrieve the instance paths of the instances associated to a source instance. OpenAssociatorInstances
Open an enumeration session to retrieve the instances associated to a source instance. OpenEnumerateInstancePaths
Open an enumeration session to enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace. OpenEnumerateInstances
Open an enumeration session to enumerate the instances of a class (including instances of its subclasses) in a namespace. OpenQueryInstances
Open an enumeration session to execute a query in a namespace and to retrieve the instances representing the query result. OpenReferenceInstancePaths
Open an enumeration session to retrieve the instance paths of the association instances that reference a source instance. OpenReferenceInstances
Open an enumeration session to retrieve the association instances that reference a source instance. PullInstancePaths
Retrieve the next set of instance paths from an open enumeration session. PullInstances
Retrieve the next set of instances (without instance paths) from an open enumeration session. PullInstancesWithPath
Retrieve the next set of instances (with instance paths) from an open enumeration session. ReferenceNames
Retrieve the instance paths of the association instances that reference a source instance, or the class paths of the association classes that reference a source class. References
Retrieve the association instances that reference a source instance, or the association classes that reference a source class. SetQualifier
Create or modify a qualifier type (= qualifier declaration) in a namespace. add_operation_recorder
Experimental: Add an operation recorder to this connection. imethodcall
Deprecated: Low-level method used by the operation-specific methods of this class. methodcall
Deprecated: Low-level method used by the InvokeMethod()
method of this class.operation_recorder_reset
Experimental: Low-level method used by the operation-specific methods of this class. operation_recorder_stage_pywbem_args
Experimental: Low-level method used by the operation-specific methods of this class. operation_recorder_stage_result
Experimental: Low-level method used by the operation-specific methods of this class. Attributes
ca_certs
Location of CA certificates (trusted certificates) for verifying the X.509 server certificate returned by the WBEM server. conn_id
Connection ID (a unique ID) of this connection. creds
Credentials for HTTP authentication with the WBEM server. debug
Boolean indicating that debug is enabled for this connection. default_namespace
Name of the CIM namespace to be used by default (if no namespace is specified for an operation). host
The {host}[:{port}]
component of the WBEM server’s URL, as specified in theurl
attribute.last_operation_time
Elapsed time of the last operation that was executed via this connection in seconds or None. last_raw_reply
CIM-XML data of the last response received from the WBEM server on this connection, formatted as it was received (=raw). last_raw_request
CIM-XML data of the last request sent to the WBEM server on this connection, formatted as it was sent (=raw). last_reply
CIM-XML data of the last response received from the WBEM server on this connection, formatted as prettified XML. last_reply_len
The size of the HTTP body in the CIM-XML response of the last operation, in Bytes. last_request
CIM-XML data of the last request sent to the WBEM server on this connection, formatted as prettified XML. last_request_len
The size of the HTTP body in the CIM-XML request of the last operation, in Bytes. last_server_response_time
Server-measured response time of the last request, or None. no_verification
Boolean indicating that verifications are disabled for this connection. operation_recorder
Deprecated: The operation recorder that was last added to the connection, or None if the connection does not currently have any recorders. operation_recorder_enabled
Experimental: Enablement status for all operation recorders of the connection. operation_recorders
Experimental: The operation recorders of this connection. statistics
Statistics for this connection. stats_enabled
Statistics enablement status for this connection. timeout
Timeout in seconds, for requests sent to the server. url
URL of the WBEM server. use_pull_operations
Boolean indicating that the client should attempt the use of pull operations in any Iter…() methods. verify_callback
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. x509
X.509 client certificate and key file to be presented to the WBEM server during the TLS/SSL handshake. Details
-
url
¶ URL of the WBEM server.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: unicode string
-
creds
¶ Credentials for HTTP authentication with the WBEM server.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: tuple()
-
default_namespace
¶ Name of the CIM namespace to be used by default (if no namespace is specified for an operation).
For details, see the description of the same-named init parameter of
this class
.This attribute is settable.
Type: unicode string
-
x509
¶ X.509 client certificate and key file to be presented to the WBEM server during the TLS/SSL handshake.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: dict
-
verify_callback
¶ 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.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: callable
-
ca_certs
¶ Location of CA certificates (trusted certificates) for verifying the X.509 server certificate returned by the WBEM server.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: string
-
no_verification
¶ Boolean indicating that verifications are disabled for this connection.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: bool
-
timeout
¶ Timeout in seconds, for requests sent to the server.
New in pywbem 0.8.
For details, see the description of the same-named init parameter of
this class
.This attribute is settable, but setting it has been deprecated.
Type: number
-
operation_recorders
¶ - Experimental: The operation recorders of this connection.
New in pywbem 0.12 as experimental.
Type: Tuple of BaseOperationRecorder
subclass objects
-
operation_recorder
¶ Deprecated: The operation recorder that was last added to the connection, or None if the connection does not currently have any recorders.
New in pywbem 0.9 as experimental. Deprecated since pywbem 0.12.
Instead of using this deprecated property, the
operation_recorders
property should be used to retrieve the recorders of the connection, and theadd_operation_recorder()
method should be used to add a recorder.This property is settable; setting this property will cause the specified operation recorder to be added to the connection as if
add_operation_recorder()
was used. None is not permitted as a new value for this property.Raises: ValueError
– Operation recorder must not be None.ValueError
– Cannot add the same recorder class multiple times.
Type:
-
host
¶ The
{host}[:{port}]
component of the WBEM server’s URL, as specified in theurl
attribute.New in pywbem 0.11.
Type: unicode string
-
operation_recorder_enabled
¶ Experimental: Enablement status for all operation recorders of the connection.
New in pywbem 0.11 as experimental
This is a writeable property; setting this property will change the operation recorder enablement status accordingly for all operation recorders of the connection.
Reading this property returns True if one or more operation recorders of the connection are enabled. Otherwise it returns False, also when the connection has no operation recorders.
Type: bool
-
stats_enabled
¶ Statistics enablement status for this connection.
New in pywbem 0.11 as experimental and finalized in 0.12.
This is a writeable property; setting this property will change the statistics enablement status accordingly.
The statistics enablement status can also be set when creating a connection, through the
stats_enabled
init argument ofWBEMConnection
.Type: bool
-
statistics
¶ Statistics for this connection.
New in pywbem 0.11 as experimental and finalized in 0.12.
Statistics are disabled by default and can be enabled via the
stats_enabled
argument when creating a connection object, or later via modifying thestats_enabled
property on this connection object. See the WBEM operation statistics section for more details.Type: Statistics
-
last_operation_time
¶ Elapsed time of the last operation that was executed via this connection in seconds or None.
New in pywbem 0.11 as experimental and finalized in 0.12.
This time is available only subsequent to the execution of an operation on this connection, and if the statistics are enabled on this connection. Otherwise, the value is None.
Type: float
-
last_server_response_time
¶ Server-measured response time of the last request, or None.
New in pywbem 0.11 as experimental and finalized in 0.12.
This time is optionally returned from the server in the HTTP header of the response. This time is available only subsequent to the execution of an operation on this connection if the WBEMServerResponseTime is received from the WBEM server. Otherwise, the value is None.
Type: float
-
use_pull_operations
¶ Boolean indicating that the client should attempt the use of pull operations in any Iter…() methods.
New in pywbem 0.11 as experimental and finalized in 0.13.
This property reflects the intent of the user as specified in the same-named init parameter of
this class
. This property is not updated with the status of actually using pull operations. That status is maintained internally for each pull operation separately to accomodate WBEM servers that support only some of the pull operations.Type: bool
-
debug
¶ Boolean indicating that debug is enabled for this connection.
When enabled (value True), the prettified last CIM-XML request and response will be stored in the following properties of this class:
When disabled (value False), these properties will be None.
This attribute is writeable. The initial value of this attribute is False.
Note that the following properties will be set regardless of whether debug is enabled for this connection:
Type: bool
-
last_request
¶ CIM-XML data of the last request sent to the WBEM server on this connection, formatted as prettified XML.
This property is only set when debug is enabled (see
debug
), and is None otherwise.Prior to sending the very first request on this connection object, this property is None.
Type: unicode string
-
last_raw_request
¶ CIM-XML data of the last request sent to the WBEM server on this connection, formatted as it was sent (=raw).
Prior to sending the very first request on this connection object, this property is None.
As of pywbem 0.13, this property is set independently of whether debug is enabled (see
debug
).Type: unicode string
-
last_reply
¶ CIM-XML data of the last response received from the WBEM server on this connection, formatted as prettified XML.
This property is only set when debug is enabled (see
debug
), and is None otherwise.This property is set to None in the WBEM operation methods of this class before the request is sent to the WBEM server, and is set to the prettified response when the response has been received from the WBEM server and XML parsed. If the XML parsing fails, this property will be None, but the
last_raw_reply
property does not depend on XML parsing and will already have been set at that point.Prior to sending the very first request on this connection object, this property is None.
Type: unicode string
-
last_raw_reply
¶ CIM-XML data of the last response received from the WBEM server on this connection, formatted as it was received (=raw).
This property is set to None in the WBEM operation methods of this class before the request is sent to the WBEM server, and is set to the prettified response when the response has been received from the WBEM server, and before XML parsing takes place.
Prior to sending the very first request on this connection object, this property is None.
As of pywbem 0.13, this property is set independently of whether debug is enabled (see
debug
).Type: unicode string
-
last_request_len
¶ The size of the HTTP body in the CIM-XML request of the last operation, in Bytes.
Prior to sending the very first request on this connection object, this property is 0.
This property is set independently of whether debug is enabled (see
debug
).Type: int
-
last_reply_len
¶ The size of the HTTP body in the CIM-XML response of the last operation, in Bytes.
This property is set to 0 in the WBEM operation methods of this class before the request is sent to the WBEM server, and is set to the size when the response has been received from the WBEM server, and before XML parsing takes place.
Prior to sending the very first request on this connection object, this property is 0.
This property is set independently of whether debug is enabled (see
debug
).Type: int
-
conn_id
¶ Connection ID (a unique ID) of this connection.
The value for this property is created when the
WBEMConnection
object is created and remains constant throughout the life of that object.The connection ID is part of each log entry output to uniquely identify the
WBEMConnection
object responsible for that log. It also part of the logger name for the “pywbem.api” and “pywbem.http” loggers that create log entries so that logging can be defined separately for different connections.Type: connection id
-
__str__
()[source]¶ Return a short representation of the
WBEMConnection
object for human consumption.
-
__repr__
()[source]¶ Return a representation of the
WBEMConnection
object with all attributes (except for the password in the credentials) that is suitable for debugging.
-
add_operation_recorder
(operation_recorder)[source]¶ Experimental: Add an operation recorder to this connection.
New in pywbem 0.12 as experimental.
If the connection already has a recorder with the same class, the request to add the recorder is ignored.
Parameters: operation_recorder (
BaseOperationRecorder
subclass object) – The operation recorder to be added. Must not be None.Raises: ValueError
– Operation recorder must not be None.ValueError
– Cannot add the same recorder class multiple times.
-
operation_recorder_reset
(pull_op=False)[source]¶ Experimental: Low-level method used by the operation-specific methods of this class.
New in pywbem 0.9 as experimental.
It resets the operation processing state of all recorders of this connection, to be ready for processing a new operation call.
-
operation_recorder_stage_pywbem_args
(method, **kwargs)[source]¶ Experimental: Low-level method used by the operation-specific methods of this class.
New in pywbem 0.9 as experimental.
It forwards the operation method name and arguments to all recorders of this connection.
-
operation_recorder_stage_result
(ret, exc)[source]¶ Experimental: Low-level method used by the operation-specific methods of this class.
New in pywbem 0.9 as experimental.
It forwards the operation results including exceptions that were raised, to all recorders of this connection, and causes the forwarded information to be recorded by all recorders of this connection.
-
imethodcall
(methodname, namespace, response_params_rqd=False, **params)[source]¶ Deprecated: Low-level method used by the operation-specific methods of this class.
Deprecated since pywbem 0.12.
Calling this function directly has been deprecated and will issue a DeprecationWarning. Users should call the operation-specific methods (e.g. GetInstance) instead of this method. This method will be removed in the next pywbem release after 0.12.
-
methodcall
(methodname, localobject, Params=None, **params)[source]¶ Deprecated: Low-level method used by the
InvokeMethod()
method of this class.Deprecated since pywbem 0.12.
Calling this function directly has been deprecated and will issue a DeprecationWarning. Users should call
InvokeMethod()
instead of this method. This method will be removed in the next pywbem release after 0.12.
-
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 aCIMClassName
object, its host attribute will be ignored. - namespace (string) –
Name of the CIM namespace to be used (case independent).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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()
andEnumerateClassNames()
is different. - IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instances, 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 qualifiers to be returned in this operation.
- 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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.
- **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 aCIMInstanceName
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
.- ClassName (string or
-
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 aCIMClassName
object, its host attribute will be ignored. - namespace (string) –
Name of the CIM namespace to be used (case independent).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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. - **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
.- ClassName (string or
-
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 qualifiers to be returned in this operation.
- 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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.
- **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 aCIMInstanceName
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
.- InstanceName (
-
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.
The PropertyList parameter determines the set of properties that are designated to be modified (see its description for details).
The properties provided in the ModifiedInstance parameter specify the new property values for the properties that are designated to be modified.
Pywbem sends the property values provided in the ModifiedInstance parameter to the WBEM server as provided; it does not add any default values for properties not provided but designated to be modified, nor does it reduce the properties by those not designated to be modified.
The properties that are actually modified by the WBEM server as a result of this operation depend on a number of things:
The WBEM server will reject modification requests for key properties and for properties that are not exposed by the creation class of the target instance.
The WBEM server may consider some properties as read-only, as a result of requirements at the CIM modeling level (schema or management profiles), or as a result of an implementation decision.
Note that the WRITE qualifier on a property is not a safe indicator as to whether the property can actually be modified. It is an expression at the level of the CIM schema that may or may not be considered in DMTF management profiles or in implementations. Specifically, a qualifier value of True on a property does not guarantee modifiability of the property, and a value of False does not prevent modifiability.
The WBEM server may detect invalid new values or conflicts resulting from the new property values and may reject modification of a property for such reasons.
If the WBEM server rejects modification of a property for any reason, it will cause this operation to fail and will not modify any property on the target instance. If this operation succeeds, all properties designated to be modified have their new values (see the description of the ModifiedInstance parameter for details on how the new values are determined).
Note that properties (including properties not designated to be modified) may change their values as an indirect result of this operation. For example, a property that was not designated to be modified may be derived from another property that was modified, and may show a changed value due to that.
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 (including None for NULL). If a property is designated to be modified but is not specified in this object, the WBEM server will use the default value of the property declaration if specified (including None), and otherwise may update the property to any value (including None).
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 qualifiers to be modified.
- PropertyList (string or iterable of string) –
This parameter defines which properties are designated to be modified.
This parameter is an iterable specifying the names of the properties, or a string that specifies a single property name. In all cases, the property names are matched case insensitively. The specified properties are designated to be modified. Properties not specified are not designated to be modified.
An empty iterable indicates that no properties are designated to be modified.
If None, DSP0200 states that the properties with values different from the current values in the instance are designated to be modified, but for all practical purposes this is equivalent to stating that all properties exposed by the instance are designated to be modified.
- **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).
New in pywbem 0.9.
If None, defaults to the namespace in the path attribute of the NewInstance parameter, or to the default namespace of the connection.
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
- **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, with classname, keybindings and namespace set.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. - **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
.- InstanceName (
-
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, or 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, selecting instance-level or class-level use of this operation, as follows:
- For selecting instance-level use: 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 selecting class-level use: 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.
- For selecting instance-level use: The instance path of the
source instance, as a
- 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 qualifiers to be returned in this operation.
- 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.
This parameter has been deprecated in DSP0200 for instance-level use. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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.
- **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 use: A list of
CIMInstance
objects that are representations of the associated instances.The path attribute of each
CIMInstance
object is aCIMInstanceName
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()
of (classpath, class) objects that are representations of the associated classes.Each tuple represents one class and has these items:
- classpath (
CIMClassName
): The class path of the class, with its attributes set as follows:- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- class (
CIMClass
): The representation of the class, with its path attribute set to the classpath tuple item.
- classpath (
Raises: Exceptions described in
WBEMConnection
.- ObjectName –
-
AssociatorNames
(ObjectName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, **extra)[source]¶ Retrieve the instance paths of the instances associated to a source instance, or 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, selecting instance-level or class-level use of this operation, as follows:
- For selecting instance-level use: 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 selecting class-level use: 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.
- For selecting instance-level use: The instance path of the
source instance, as a
- 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.
- **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 use: 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 use: 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
.- ObjectName –
-
References
(ObjectName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]¶ Retrieve the association instances that reference a source instance, or 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, selecting instance-level or class-level use of this operation, as follows:
- For selecting instance-level use: 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 selecting class-level use: 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.
- For selecting instance-level use: The instance path of the
source instance, as a
- 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 qualifiers to be returned in this operation.
- 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.
This parameter has been deprecated in DSP0200 for instance-level use. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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.
- **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 use: A list of
CIMInstance
objects that are representations of the referencing association instances.The path attribute of each
CIMInstance
object is aCIMInstanceName
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()
of (classpath, class) objects that are representations of the referencing association classes.Each tuple represents one class and has these items:
- classpath (
CIMClassName
): The class path of the class, with its attributes set as follows:- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- class (
CIMClass
): The representation of the class, with its path attribute set to the classpath tuple item.
- classpath (
Raises: Exceptions described in
WBEMConnection
.- ObjectName –
-
ReferenceNames
(ObjectName, ResultClass=None, Role=None, **extra)[source]¶ Retrieve the instance paths of the association instances that reference a source instance, or the class paths of the association classes that reference a source class.
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, selecting instance-level or class-level use of this operation, as follows:
- For selecting instance-level use: 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 selecting class-level use: 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.
- For selecting instance-level use: The instance path of the
source instance, as a
- 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.
- **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 use: 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 use: 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
.- ObjectName –
-
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 their order), followed by the set of keyword parameters (not preserving their 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 use: 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 use: 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.
- For instance-level use: The instance path of the target
instance, as a
- Params (iterable) –
An iterable of input parameter values for the CIM method. Each item in the iterable is a single parameter value and can be any of:
CIMParameter
representing a parameter value. The name, value, type and embedded_object attributes of this object are used.- tuple of name, value, with:
- name (string): Parameter name (case independent)
- value (CIM data type): Parameter value
- **params –
Each keyword parameter is an additional input parameter value for the CIM method, with:
- key (string): Parameter name (case independent)
- value (CIM data type): Parameter value
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:
- key (unicode string): Parameter name, preserving its lexical case
- value (CIM data type): Parameter value
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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
.
-
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]¶ Enumerate the instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation. This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
This method is a generator function that retrieves instances from the WBEM server and returns them one by one (using
yield
) when the caller iterates through the returned generator object. The number of instances that are retrieved from the WBEM server in one request (and thus need to be materialized in this method) is up to the MaxObjectCount parameter if the corresponding pull operations are used, or the complete result set all at once if the corresponding traditional operation is used.By default, this method attempts to perform the corresponding pull operations (
OpenEnumerateInstances()
andPullInstancesWithPath()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (EnumerateInstances()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
Filtering is not supported for the corresponding traditional operation so that setting the FilterQuery or FilterQueryLanguage parameters will be rejected if the corresponding traditional operation is used by this method.
Note that this limitation is not a disadvantage compared to using the corresponding pull operations directly, because in both cases, the WBEM server must support the pull operations and their filtering capability in order for the filtering to work.
Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as aCIMClassName
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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, the behavior depends on the underlying operation: If pull operations are used, inherited properties are not excluded. If traditional operations are used, inherited properties are basically excluded, but the behavior may be WBEM server specific.
- If None, the behavior depends on the underlying operation: If pull operations are used, inherited properties are not excluded. If traditional operations are used, 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, i.e. to exclude inherited properties.
DSP0200 has deprecated this parameter for the traditional operation and does not support it for the pull operation.
This parameter 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()
andEnumerateClassNames()
is different. - IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instances, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if this method uses traditional operations and 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.
If this method uses pull operations, this parameter will be ignored, not passed to the WBEM server, and the returned instances will not contain any qualifiers. If this method uses traditional operations, clients cannot rely on returned instances containing qualifiers, as described in DSP0200.
- 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - FilterQuery (string) –
The filter query in the query language defined by the FilterQueryLanguage parameter.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - 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 codeCIM_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.
- 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
The choice of MaxObjectCount is client/server dependent but choices between 100 and 1000 typically do not have a significant impact on either memory or overall efficiency.
- **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
. ValueError
– Invalid parameters provided.
Returns: A generator object that iterates the resulting CIM instances. These instances include an instance path that has its host and namespace components set.
Return type: generator iterating
CIMInstance
Example:
insts_generator = conn.IterEnumerateInstances('CIM_Blah') for inst in insts_generator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_generator.close() break else: print('instance {0}'.format(inst.tomof()))
-
IterEnumerateInstancePaths
(ClassName, namespace=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
This method is a generator function that retrieves instance paths from the WBEM server and returns them one by one (using
yield
) when the caller iterates through the returned generator object. The number of instance paths that are retrieved from the WBEM server in one request (and thus need to be materialized in this method) is up to the MaxObjectCount parameter if the corresponding pull operations are used, or the complete result set all at once if the corresponding traditional operation is used.By default, this method attempts to perform the corresponding pull operations (
OpenEnumerateInstancePaths()
andPullInstancePaths()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (EnumerateInstanceNames()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
Filtering is not supported for the corresponding traditional operation so that setting the FilterQuery or FilterQueryLanguage parameters will be rejected if the corresponding traditional operation is used by this method.
Note that this limitation is not a disadvantage compared to using the corresponding pull operations directly, because in both cases, the WBEM server must support the pull operations and their filtering capability in order for the filtering to work.
Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as aCIMClassName
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised.Not all WBEM servers support filtering for this operation because it returns instance paths and the act of the server filtering requires that it generate instances just for that purpose and then discard them.
- FilterQuery (string) –
The filter query in the query language defined by the FilterQueryLanguage parameter.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - 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 codeCIM_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.
- 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- 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.
- **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 generator object that iterates the resulting CIM instance paths. These instance paths have their host and namespace components set.
Return type: generator iterating
CIMInstanceName
Example:
paths_generator = conn.IterEnumerateInstancePaths('CIM_Blah') for path in paths_generator: print('path {0}'.format(path))
-
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]¶ Retrieve the instances associated to a source instance, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation. This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
This method is a generator function that retrieves instances from the WBEM server and returns them one by one (using
yield
) when the caller iterates through the returned generator object. The number of instances that are retrieved from the WBEM server in one request (and thus need to be materialized in this method) is up to the MaxObjectCount parameter if the corresponding pull operations are used, or the complete result set all at once if the corresponding traditional operation is used.By default, this method attempts to perform the corresponding pull operations (
OpenAssociatorInstances()
andPullInstancesWithPath()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (Associators()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
Filtering is not supported for the corresponding traditional operation so that setting the FilterQuery or FilterQueryLanguage parameters will be rejected if the corresponding traditional operation is used by this method.
Note that this limitation is not a disadvantage compared to using the corresponding pull operations directly, because in both cases, the WBEM server must support the pull operations and their filtering capability in order for the filtering to work.
Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).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, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if this method uses traditional operations and 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.
If this method uses pull operations, this parameter will be ignored and the returned instances will not contain any qualifiers. If this method uses traditional operations, clients cannot rely on returned instances containing qualifiers, as described in DSP0200.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - FilterQuery (string) –
The filter query in the query language defined by the FilterQueryLanguage parameter.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - 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 codeCIM_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.
Many WBEM servers do not support this request attribute so that setting it to True is NOT recommended except in special cases.
If this parameter is True and the traditional operation is used by this method,
ValueError
will be raised. - 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
- **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 generator object that iterates the resulting CIM instances. These instances include an instance path that has its host and namespace components set.
Return type: generator iterating
CIMInstance
Raises: Exceptions described in
WBEMConnection
.Example:
insts_generator = conn.IterAssociatorInstances('CIM_Blah.key=1',...) for inst in insts_generator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_generator.close() break else: print('instance {0}'.format(inst.tomof()))
-
IterAssociatorInstancePaths
(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ Retrieve the instance paths of the instances associated to a source instance, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation. This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
This method is a generator function that retrieves instance paths from the WBEM server and returns them one by one (using
yield
) when the caller iterates through the returned generator object. The number of instance paths that are retrieved from the WBEM server in one request (and thus need to be materialized in this method) is up to the MaxObjectCount parameter if the corresponding pull operations are used, or the complete result set all at once if the corresponding traditional operation is used.By default, this method attempts to perform the corresponding pull operations (
OpenAssociatorInstancePaths()
andPullInstancePaths()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (AssociatorNames()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
Filtering is not supported for the corresponding traditional operation so that setting the FilterQuery or FilterQueryLanguage parameters will be rejected if the corresponding traditional operation is used by this method.
Note that this limitation is not a disadvantage compared to using the corresponding pull operations directly, because in both cases, the WBEM server must support the pull operations and their filtering capability in order for the filtering to work.
Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised.Not all WBEM servers support filtering for this operation because it returns instance paths and the act of the server filtering requires that it generate instances just for that purpose and then discard them.
- FilterQuery (string) –
The filter query in the query language defined by the FilterQueryLanguage parameter.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - 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 codeCIM_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.
- 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
- **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 generator object that iterates the resulting CIM instance paths. These instance paths have their host and namespace components set.
Return type: generator iterating
CIMInstanceName
Raises: Exceptions described in
WBEMConnection
.Example:
paths_generator = conn.IterAssociatorInstancePaths('CIM_Blah') for path in paths_generator: print('path {0}'.format(path))
-
IterReferenceInstances
(InstanceName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ Retrieve the association instances that reference a source instance, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation. This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
This method is a generator function that retrieves instances from the WBEM server and returns them one by one (using
yield
) when the caller iterates through the returned generator object. The number of instances that are retrieved from the WBEM server in one request (and thus need to be materialized in this method) is up to the MaxObjectCount parameter if the corresponding pull operations are used, or the complete result set all at once if the corresponding traditional operation is used.By default, this method attempts to perform the corresponding pull operations (
OpenReferenceInstances()
andPullInstancesWithPath()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (References()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
Filtering is not supported for the corresponding traditional operation so that setting the FilterQuery or FilterQueryLanguage parameters will be rejected if the corresponding traditional operation is used by this method.
Note that this limitation is not a disadvantage compared to using the corresponding pull operations directly, because in both cases, the WBEM server must support the pull operations and their filtering capability in order for the filtering to work.
Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).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, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if this method uses traditional operations and 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.
If this method uses pull operations, this parameter will be ignored and the returned instances will not contain any qualifiers. If this method uses traditional operations, clients cannot rely on returned instances containing qualifiers, as described in DSP0200.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - FilterQuery (string) –
The filter query in the query language defined by the FilterQueryLanguage parameter.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - 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 codeCIM_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.
- 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
- **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 generator object that iterates the resulting CIM instances. These instances include an instance path that has its host and namespace components set.
Return type: generator iterating
CIMInstance
Raises: Exceptions described in
WBEMConnection
.Example:
insts_generator = conn.IterReferenceInstances('CIM_Blah.key=1', ...) for inst in insts_generator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_generator.close() break else: print('instance {0}'.format(inst.tomof()))
-
IterReferenceInstancePaths
(InstanceName, ResultClass=None, Role=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ Retrieve the instance paths of the association instances that reference a source instance, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation. This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
This method is a generator function that retrieves instance paths from the WBEM server and returns them one by one (using
yield
) when the caller iterates through the returned generator object. The number of instance paths that are retrieved from the WBEM server in one request (and thus need to be materialized in this method) is up to the MaxObjectCount parameter if the corresponding pull operations are used, or the complete result set all at once if the corresponding traditional operation is used.By default, this method attempts to perform the corresponding pull operations (
OpenReferenceInstancePaths()
andPullInstancePaths()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (ReferenceNames()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
Filtering is not supported for the corresponding traditional operation so that setting the FilterQuery or FilterQueryLanguage parameters will be rejected if the corresponding traditional operation is used by this method.
Note that this limitation is not a disadvantage compared to using the corresponding pull operations directly, because in both cases, the WBEM server must support the pull operations and their filtering capability in order for the filtering to work.
Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised.Not all WBEM servers support filtering for this operation because it returns instance paths and the act of the server filtering requires that it generate instances just for that purpose and then discard them.
- FilterQuery (string) –
The filter query in the query language defined by the FilterQueryLanguage parameter.
If this parameter is not None and the traditional operation is used by this method,
ValueError
will be raised. - 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 codeCIM_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.
- 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
- **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 generator object that iterates the resulting CIM instance paths. These instance paths have their host and namespace components set.
Return type: generator iterating
CIMInstanceName
Raises: Exceptions described in
WBEMConnection
.Example:
paths_generator = conn.IterReferenceInstancePaths('CIM_Blah') for path in paths_generator: print('path {0}'.format(path))
-
IterQueryInstances
(FilterQueryLanguage, FilterQuery, namespace=None, ReturnQueryResultClass=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ Execute a query in a namespace, using the Python generator idiom to return the result.
New in pywbem 0.10 as experimental and finalized in 0.12.
This method uses the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation. This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
Other than the other Iter…() methods, this method does not return a generator object directly, but as a property of the returned object. The reason for this design is the additionally returned query result class. The generator property in the returned object is a generator object that returns the instances in the query result one by one (using
yield
) when the caller iterates through the generator object. This design causes the entire query result to be materialized, even if pull operations are used.By default, this method attempts to perform the corresponding pull operations (
OpenQueryInstances()
andPullInstances()
). If these pull operations are not supported by the WBEM server, this method falls back to using the corresponding traditional operation (ExecQuery()
). Whether the WBEM server supports these pull operations is remembered in theWBEMConnection
object (by operation type), and avoids unnecessary attempts to try these pull operations on that connection in the future. The use_pull_operations init parameter ofWBEMConnection
can be used to control the preference for always using pull operations, always using traditional operations, or using pull operations if supported by the WBEM server (the default).This method provides all of the controls of the corresponding pull operations except for the ability to set different response sizes on each request; the response size (defined by the MaxObjectCount parameter) is the same for all pull operations in the enumeration session.
In addition, some functionality is only available if the corresponding pull operations are used by this method:
- Setting the ContinueOnError parameter to True will be rejected if the corresponding traditional operation is used by this method.
The enumeration session that is opened with the WBEM server when using pull operations is closed automatically when the returned generator object is exhausted, or when the generator object is closed using its
close()
method (which may also be called before the generator is exhausted).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. Because this is not a filter query, “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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- ReturnQueryResultClass (
bool
) –Controls whether a class definition describing the returned instances will be returned.
None will cause the server to use its default of False.
None will cause the server to use its default of False.
- 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 codeCIM_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.
- 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
- 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 codeCIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
. If the corresponding traditional operation is used by this method,ValueError
will be raised. - 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.
- 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
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for open and all pull requests issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
- **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: An object with the following properties:
query_result_class (
CIMClass
):The query result class, if requested via the ReturnQueryResultClass parameter.
None, if a query result class was not requested.
generator (generator iterating
CIMInstance
):A generator object that iterates the CIM instances representing the query result. These instances do not have an instance path set.
Return type: IterQueryInstancesReturn
Raises: Exceptions described in
WBEMConnection
.Example:
result = conn.IterQueryInstances( 'DMTF:CQL', 'SELECT FROM * where pl > 2') for inst in result.generator: print('instance {0}'.format(inst.tomof()))
-
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 enumerate the instances of a class (including instances of its subclasses) in a namespace.
New in pywbem 0.9.
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 the
PullInstancesWithPath()
method to retrieve the next set of instances or theCloseEnumeration()
method to close the enumeration session before it is exhausted.Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as aCIMClassName
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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
) –Deprecated: Controls the exclusion of inherited properties from the returned instances.
Deprecated since pywbem 0.14.
This parameter has been deprecated in pywbem and will be ignored and not passed on to the WBEM server, because this parameter was never defined in DSP0200 and thus will be rejected by WBEM servers.
- 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()
andEnumerateClassNames()
is different. - IncludeQualifiers (
bool
) –Deprecated: Indicates that qualifiers are to be included in the returned instances.
Deprecated since pywbem 0.14.
This parameter has been deprecated in pywbem and will be ignored and not passed on to the WBEM server, because this parameter was never defined in DSP0200 and thus will be rejected 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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) – The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
- FilterQuery (string) – The filter query in 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstance
): Representations of the retrieved instances.The path attribute of each
CIMInstance
object is aCIMInstanceName
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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.Example:
max_object_count = 100 rslt_tuple = conn.OpenEnumerateInstances( 'CIM_Blah', MaxObjectCount=max_object_count) insts = rslt_tuple.paths while not rslt_tuple.eos: rslt_tuple = conn.PullInstancesWithPath(rslt_tupl.context, max_object_count) insts.extend(rslt_tupl.paths) for inst in insts: print('instance {0}'.format(inst.tomof()))
- ClassName (string or
-
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.
New in pywbem 0.9.
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 the
PullInstancePaths()
method to retrieve the next set of instance paths or theCloseEnumeration()
method to close the enumeration session before it is exhausted.Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as aCIMClassName
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
Not all WBEM servers support filtering for this operation because it returns instance paths and the act of the server filtering requires that it generate instances just for that purpose and then discard them.
- FilterQuery (string) – The filter query in 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstanceName
): Representations of the retrieved 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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.Example:
max_object_count = 100 rslt_tuple = conn.OpenEnumerateInstancePaths( 'CIM_Blah', MaxObjectCount=max_object_count) paths = rslt_tuple.paths while not rslt_tuple.eos: rslt_tuple = conn.PullInstancePaths(rslt_tupl.context, max_object_count) paths.extend(rslt_tupl.paths) for path in paths: print('path {0}'.format(path))
- ClassName (string or
-
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.
New in pywbem 0.9.
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.
Use the
PullInstancesWithPath()
method to retrieve the next set of instances or theCloseEnumeration()
method to close the enumeration session before it is exhausted.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
) –Deprecated: Indicates that qualifiers are to be included in the returned instances.
Deprecated since pywbem 0.14.
This parameter has been deprecated in pywbem and will be ignored and not passed on to the WBEM server, because this parameter was never defined in DSP0200 and thus will be rejected by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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) – The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
- FilterQuery (string) – The filter query in 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstance
): Representations of the retrieved instances.The path attribute of each
CIMInstance
object is aCIMInstanceName
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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- InstanceName (
-
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.
New in pywbem 0.9.
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 the
PullInstancePaths()
method to retrieve the next set of instance paths or theCloseEnumeration()
method to close the enumeration session before it is exhausted.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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
Not all WBEM servers support filtering for this operation because it returns instance paths and the act of the server filtering requires that it generate instances just for that purpose and then discard them.
- FilterQuery (string) – The filter query in 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstanceName
): Representations of the retrieved 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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- InstanceName (
-
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.
New in pywbem 0.9.
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 the
PullInstancesWithPath()
method to retrieve the next set of instances or theCloseEnumeration()
method to close the enumeration session before it is exhausted.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
) –Deprecated: Indicates that qualifiers are to be included in the returned instances.
Deprecated since pywbem 0.14.
This parameter has been deprecated in pywbem and will be ignored and not passed on to the WBEM server, because this parameter was never defined in DSP0200 and thus will be rejected by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method 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.
This parameter has been deprecated in DSP0200. WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- PropertyList (string or iterable of 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) – The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
- FilterQuery (string) – The filter query in 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstance
): Representations of the retrieved instances.The path attribute of each
CIMInstance
object is aCIMInstanceName
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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- InstanceName (
-
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.
New in pywbem 0.9.
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 the
PullInstancePaths()
method to retrieve the next set of instance paths or theCloseEnumeration()
method to close the enumeration session before it is exhausted.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) –
The name of the filter query language used for the FilterQuery parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
Not all WBEM servers support filtering for this operation because it returns instance paths and the act of the server filtering requires that it generate instances just for that purpose and then discard them.
- FilterQuery (string) – The filter query in 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstanceName
): Representations of the retrieved 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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- InstanceName (
-
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 and to retrieve the instances representing the query result.
New in pywbem 0.9.
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.
Use the
PullInstances()
method to retrieve the next set of instances or theCloseEnumeration()
method to close the enumeration session before it is exhausted.Parameters: - FilterQueryLanguage (string) – Name of the query language used in the FilterQuery parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. Because this is not a filter query, “DMTF:FQL” is not a valid query language for this request.
- FilterQuery (string) – Query string in the query language specified in the FilterQueryLanguage parameter.
- namespace (string) –
Name of the CIM namespace to be used (case independent).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- ReturnQueryResultClass (
bool
) –Controls whether a class definition describing the returned instances will be returned.
None will cause the server to use its default of False.
- 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 codeCIM_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.
- 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
- 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 codeCIM_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.
- 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
- 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.
- **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
ofCIMInstance
): Representations of the retrieved 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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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 instance paths) from an open enumeration session.
New in pywbem 0.9.
This operation can only be used on enumeration sessions that have been opened by one of the following methods:
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 (
tuple()
of server_context, namespace) –A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session.
The tuple items are:
- 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.
- **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
ofCIMInstance
): Representations of the retrieved instances.The path attribute of each
CIMInstance
object is aCIMInstanceName
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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- context (
-
PullInstancePaths
(context, MaxObjectCount, **extra)[source]¶ Retrieve the next set of instance paths from an open enumeration session.
New in pywbem 0.9.
This operation can only be used on enumeration sessions that have been opened by one of the following methods:
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 (
tuple()
of server_context, namespace) –A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session.
The tuple items are:
- 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.
- **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
ofCIMInstanceName
): Representations of the retrieved 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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- context (
-
PullInstances
(context, MaxObjectCount, **extra)[source]¶ Retrieve the next set of instances (without instance paths) from an open enumeration session.
New in pywbem 0.9.
This operation can only be used on enumeration sessions that have been opened by one of the following methods:
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 (
tuple()
of server_context, namespace) –A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session.
The tuple items are:
- 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.
- **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
ofCIMInstance
): Representations of the retrieved 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 this operation:- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted and the context item is the context object for the next operation on the enumeration session.
context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for 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
.- context (
-
CloseEnumeration
(context, **extra)[source]¶ Close an open enumeration session, causing an early termination of an incomplete enumeration session.
New in pywbem 0.9.
This method performs the CloseEnumeration operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
The enumeration session must still be open when this operation is performed.
If the operation succeeds, this method returns. Otherwise, it raises an exception.
Parameters: - context (
tuple()
of server_context, namespace) –A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session.
The tuple items are:
- **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
.- context (
-
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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 True.
- 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.
- **extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A list of
CIMClass
objects that are representations of the enumerated classes, with their path attributes set.Raises: Exceptions described in
WBEMConnection
.- namespace (string) –
-
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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. - **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
.- namespace (string) –
-
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 aCIMClassName
object, its host attribute will be ignored. - namespace (string) –
Name of the namespace of the class to be retrieved (case independent).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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 True.
- 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 (string or iterable of 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.
- **extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
CIMClass
object that is a representation of the retrieved class, with its path attribute set.Raises: Exceptions described in
WBEMConnection
.- ClassName (string or
-
ModifyClass
(ModifiedClass, namespace=None, **extra)[source]¶ Modify a class.
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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
.- ModifiedClass (
-
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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
.- NewClass (
-
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 aCIMClassName
object, its host attribute will be ignored. - namespace (string) –
Name of the namespace of the class to be deleted (case independent).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
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. - **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
.- ClassName (string or
-
EnumerateQualifiers
(namespace=None, **extra)[source]¶ Enumerate the qualifier types (= 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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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
.- namespace (string) –
-
GetQualifier
(QualifierName, namespace=None, **extra)[source]¶ Retrieve a qualifier type (= qualifier declaration).
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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 type (= 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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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
.- QualifierDeclaration (
-
DeleteQualifier
(QualifierName, namespace=None, **extra)[source]¶ Delete a qualifier type (= qualifier declaration).
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).
Leading and trailing slash characters will be stripped. The lexical case will be preserved.
If None, the default namespace of the connection object will be used.
- **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
.
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, both as a parameter value in a method invocation and as a parameter declaration in a CIM method declaration in a CIM class |
CIMQualifier |
CIM qualifier value |
CIMQualifierDeclaration |
CIM qualifier type/declaration |
Putting CIM objects in sets¶
Using sets for holding the result of WBEM operations is not uncommon, because that allows comparison of results without regard to the (undefined) order in which the objects are returned.
CIM objects are mutable and unchanged-hashable. This requires some caution when putting them in sets, or using them in any other way that relies on their hash values.
The caution that is needed is that the public attributes, and therefore the state of the CIM objects, must not change as long as they are a member of a set, or used in any other way that relies on their hash values.
The following example shows what happens if a CIM object is modified while being a member of a set:
import pywbem
s = set()
# Create CIM object c1 and show its identity and hash value:
c1 = pywbem.CIMClass('C')
print(id(c1), hash(c1)) # (140362966049680, -7623128493967117119)
# Add c1 to the set and verify the set content:
s.add(c1)
print([id(c) for c in s]) # [140362966049680]
# Modify the c1 object; it now has changed its hash value:
c1.superclass = 'B'
print(id(c1), hash(c1)) # (140362966049680, 638672161836520435)
# Create a CIM object c2 with the same attribute values as c1, and show
# that they compare equal and that c2 has the same hash value as c1 now has:
c2 = pywbem.CIMClass('C', superclass='B')
print(c1 == c2) # True
print(id(c2), hash(c2)) # (140362970983696, 638672161836520435)
# Add c2 to the set and verify the set content:
s.add(c2)
print([id(c) for c in s]) # [140362966049680, 140362970983696] !!
At the end, the set contains both objects even though they have the same hash value. This is not what one would expect from set types.
The reason is that at the time the object c1 was added to the set, it had a different hash value, and the set uses the hash value it found at insertion time of its member for identifying the object. When the second object is added, it finds it has a yet unknown hash value, and adds it.
While the set type in this particular Python implementation was able to still look up the first member object even though its hash value has changed meanwhile, other collection types or other Python implementations may not be as forgiving and may not even be able to look up the object once its hash value has changed.
Therefore, always make sure that the public attributes of CIM objects that are put into a set remain unchanged while the object is in the set. The same applies to any other usage of CIM objects that relies on their hash values.
Order of CIM child objects¶
CIM objects have zero or more lists of child objects. For example, a CIM class (the parent object) has a list of CIM properties, CIM methods and CIM qualifiers (the child objects).
In pywbem, the parent CIM object allows initializing each list of child objects
via an init parameter. For example, the CIMClass
init method
has a parameter named properties
that allows specifying the CIM properties
of the CIM class.
Once the parent CIM object exists, each list of child objects can be modified
via a settable attribute. For example, the CIMClass
class has
a properties
attribute for its list of CIM properties.
For such attributes and init parameters that specify lists of child objects, pywbem supports a number of different ways the child objects can be specified.
Some of these ways preserve the order of child objects and some don’t.
This section uses CIM properties in CIM classes as an example, but it applies to all kinds of child objects in CIM objects.
The possible input objects for the properties
init parameter
and for the properties
attribute of
CIMClass
is described in the type
properties input object, and must be one of these objects:
- iterable of
CIMProperty
- iterable of tuple(key, value)
OrderedDict
with key and valuedict
with key and value (will not preserve order)
The keys are always the property names, and the values are always
CIMProperty
objects (at least when initializing classes).
Even though the OrderedDict
class preserves the order
of its items, intializing the dictionary with keyword arguments causes the
order of items to be lost before the dictionary is even initialized (before
Python 3.6). The only way to initialize a dictionary without loosing order of
items is by providing a list of tuples(key,value).
The following examples work but loose the order of properties in the class:
# Examples where order of properties in class is not as specified:
# Using an OrderedDict object, initialized with keyword arguments
# (before Python 3.6):
c1_props = OrderedDict(
Prop1=CIMProperty('Prop1', value='abc'),
Prop2=CIMProperty('Prop2', value=None, type='string'),
)
# Using a dict object, initialized with keyword arguments (This time
# specified using key:value notation):
c1_props = {
'Prop1': CIMProperty('Prop1', value='abc'),
'Prop2': CIMProperty('Prop2', value=None, type='string'),
}
# Using a dict object, initialized with list of tuple(key,value):
c1_props = dict([
('Prop1', CIMProperty('Prop1', value='abc')),
('Prop2', CIMProperty('Prop2', value=None, type='string')),
])
# Any of the above objects can be used to initialize the class properties:
c1 = CIMClass('CIM_Foo', properties=c1_props)
The following examples all preserve the order of properties in the class:
# Examples where order of properties in class is as specified:
# Using a list of CIMProperty objects (starting with pywbem 0.12):
c1_props = [
CIMProperty('Prop1', value='abc'),
CIMProperty('Prop2', value=None, type='string'),
]
# Using an OrderedDict object, initialized with list of tuple(key,value):
c1_props = OrderedDict([
('Prop1', CIMProperty('Prop1', value='abc')),
('Prop2', CIMProperty('Prop2', value=None, type='string')),
])
# Using a list of tuple(key,value):
c1_props = [
('Prop1', CIMProperty('Prop1', value='abc')),
('Prop2', CIMProperty('Prop2', value=None, type='string')),
]
# Any of the above objects can be used to initialize the class properties:
c1 = CIMClass('CIM_Foo', properties=c1_props)
NocaseDict¶
Class NocaseDict
is a dictionary implementation with case-insensitive but
case-preserving keys, and with preservation of the order of its items.
It is used for lists of child objects of CIM objects (e.g. the list of CIM properties in a CIM class, or the list of CIM parameters in a CIM method).
Users of pywbem will notice NocaseDict
objects only as a result of pywbem
functions. Users cannot create NocaseDict
objects.
Except for the case-insensitivity of its keys, it behaves like the built-in
OrderedDict
. Therefore, NocaseDict
is not
described in detail in this documentation.
Deprecated: In pywbem 0.9, 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 CIM instance name).
A CIM instance path references a CIM instance in a CIM namespace in a WBEM server. Namespace and WBEM server may be unspecified.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
Parameters: - classname (string) –
Name of the creation class of the referenced instance.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- keybindings (keybindings input object) – Keybindings for the instance path (that is, the key property values of the referenced instance).
- host (string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced instance.
The format of the string must be:
host[:port]
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986
with the extensions for zone identifiers as defined in
RFC6874, supporting
-
(minus) for the delimiter before the zone ID string, as an additional choice to%25
.
None means that the WBEM server is unspecified, and the
host
attribute will also be None.The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- namespace (string) –
Name of the CIM namespace containing the referenced instance.
None means that the namespace is unspecified, and the
namespace
attribute will also be None.Leading and trailing slash characters will be stripped. The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
Raises: ValueError
– An error in the provided argument values.ValueError
– A keybinding value is None and the config variable IGNORE_NULL_KEY_VALUE is FalseTypeError
– An error in the provided argument types.
Methods
copy
Return a new CIMInstanceName
object that is a copy of this CIM instance path.from_instance
Return a new CIMInstanceName
object from the key property values in a CIM instance and the key property definitions in a CIM class.from_wbem_uri
Return a new CIMInstanceName
object from the specified WBEM URI string.get
Return the value of a particular keybinding of this CIM instance path, or a default value. has_key
Return a boolean indicating whether this CIM instance path has a particular keybinding. items
Return a copied list of the keybinding names and values of this CIM instance path. iteritems
Iterate through the keybinding names and values of this CIM instance path. iterkeys
Iterate through the keybinding names of this CIM instance path. itervalues
Iterate through the keybinding values of this CIM instance path. keys
Return a copied list of the keybinding names of this CIM instance path. to_wbem_uri
Return the (untyped) WBEM URI string of this CIM instance path. tocimxml
Return the CIM-XML representation of this CIM instance path, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM instance path, as a unicode string. update
Update the keybindings of this CIM instance path. values
Return a copied list of the keybinding values of this CIM instance path. Attributes
classname
Class name of this CIM instance path, identifying the creation class of the referenced instance. host
Host and optionally port of this CIM instance path, identifying the WBEM server of the referenced instance. keybindings
Keybindings of this CIM instance path, identifying the key properties of the referenced instance. namespace
Namespace name of this CIM instance path, identifying the namespace of the referenced instance. Details
-
classname
¶ Class name of this CIM instance path, identifying the creation class of the referenced instance.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
keybindings
¶ Keybindings of this CIM instance path, identifying the key properties of the referenced instance.
Will not be None.
Each dictionary item specifies one keybinding, with:
- key (unicode string): Keybinding name. Its lexical case was preserved.
- value (CIM data type or number): Keybinding value. If the config variable IGNORE_NULL_KEY_VALUE is True, None is allowed as a key value.
The order of keybindings in the instance path is preserved.
The keybinding name may be None in objects of this class that are created by pywbem, in the special case a WBEM server has returned an instance path with an unnamed keybinding (i.e. a KEYVALUE or VALUE.REFERENCE element without a parent KEYBINDINGS element). This is allowed as per DSP0201. When creating objects of this class, it is not allowed to specify unnamed keybindings, i.e. the keybinding name must not be None.
This attribute is settable; setting it will cause the current keybindings to be replaced with the new keybindings. For details, see the description of the same-named init parameter of
this class
.The keybindings can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be specified as a CIM data type or as number:
instpath = CIMInstanceName(...) v1 = "abc" # must be a CIM data type or Python number type instpath.keybindings['k1'] = v1 # Set "k1" to v1 (add if needed) v1 = instpath.keybindings['k1'] # Access value of "k1" del instpath.keybindings['k1'] # Delete "k1" from the inst. path
In addition, the keybindings can be accessed and manipulated one by one by using the entire
CIMInstanceName
object like a dictionary. Again, the provided input value must be specified as a CIM data type or as number:instpath = CIMInstanceName(...) v2 = 42 # must be a CIM data type or Python number type instpath['k2'] = v2 # Set "k2" to v2 (add if needed) v2 = instpath['k2'] # Access value of "k2" del instpath['k2'] # Delete "k2" from the instance path
Type: NocaseDict
-
namespace
¶ Namespace name of this CIM instance path, identifying the namespace of the referenced instance.
None means that the namespace is unspecified.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
host
¶ Host and optionally port of this CIM instance path, identifying the WBEM server of the referenced instance.
For details about the string format, see the same-named init parameter of
this class
.None means that the host and port are unspecified.
This attribute is settable. For details, see the description of the same-named init parameter.
Type: unicode string
-
__str__
()[source]¶ Return the WBEM URI string of this CIM instance path.
The returned WBEM URI string is in the historical format returned by
to_wbem_uri()
.For new code, it is recommended that the standard format is used; it is returned by
to_wbem_uri()
as the default format.Examples (for the historical format):
With host and namespace:
//acme.com/cimv2/test:CIM_RegisteredProfile.InstanceID="acme.1"
Without host but with namespace:
cimv2/test:CIM_RegisteredProfile.InstanceID="acme.1"
Without host and without namespace:
CIM_RegisteredProfile.InstanceID="acme.1"
-
__repr__
()[source]¶ Return a string representation of this CIM instance path, that is suitable for debugging.
The key bindings will be ordered by their names in the result.
-
copy
()[source]¶ Return a new
CIMInstanceName
object that is a copy of this CIM instance path.This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:
- Any mutable object types (see CIM data types) in the
keybindings
dictionary (but not the dictionary object itself)
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.- Any mutable object types (see CIM data types) in the
-
update
(*args, **kwargs)[source]¶ Update the keybindings of this CIM instance path.
Existing keybindings will be updated, and new keybindings will be added.
Parameters: - *args (list) – Keybindings for updating the keybindings of the instance path,
specified as positional arguments. Each positional argument must
be a tuple (key, value), where key and value are described for
setting the
keybindings
property. - **kwargs (dict) – Keybindings for updating the keybindings of the instance path,
specified as keyword arguments. The name and value of the keyword
arguments are described as key and value for setting the
keybindings
property.
- *args (list) – Keybindings for updating the keybindings of the instance path,
specified as positional arguments. Each positional argument must
be a tuple (key, value), where key and value are described for
setting the
-
has_key
(key)[source]¶ Return a boolean indicating whether this CIM instance path has a particular keybinding.
Parameters: key (string) – Name of the keybinding (in any lexical case). Returns: Boolean indicating whether this CIM instance path has the keybinding. Return type: bool
-
get
(key, default=None)[source]¶ Return the value of a particular keybinding of this CIM instance path, or a default value.
New in pywbem 0.8.
Parameters: - key (string) – Name of the keybinding (in any lexical case).
- default (CIM data type) – Default value that is returned if a keybinding with the specified name does not exist in the instance path.
Returns: Value of the keybinding, or the default value.
Return type:
-
keys
()[source]¶ Return a copied list of the keybinding names of this CIM instance path.
The keybinding names have their original lexical case.
The order of keybindings is preserved.
-
values
()[source]¶ Return a copied list of the keybinding values of this CIM instance path.
The order of keybindings is preserved.
-
items
()[source]¶ Return a copied list of the keybinding names and values of this CIM instance path.
Each item in the returned list is a tuple of keybinding name (in the original lexical case) and keybinding value.
The order of keybindings is preserved.
-
iterkeys
()[source]¶ Iterate through the keybinding names of this CIM instance path.
The keybinding names have their original lexical case.
The order of keybindings is preserved.
-
itervalues
()[source]¶ Iterate through the keybinding values of this CIM instance path.
The order of keybindings is preserved.
-
iteritems
()[source]¶ Iterate through the keybinding names and values of this CIM instance path.
Each iteration item is a tuple of the keybinding name (in the original lexical case) and the keybinding value.
The order of keybindings is preserved.
-
tocimxml
(ignore_host=False, ignore_namespace=False)[source]¶ Return the CIM-XML representation of this CIM instance path, as an object of an appropriate subclass of Element.
If the instance path has no namespace specified or if ignore_namespace is True, the returned CIM-XML representation is an INSTANCENAME element consistent with DSP0201.
Otherwise, if the instance path has no host specified or if ignore_host is True, the returned CIM-XML representation is a LOCALINSTANCEPATH element consistent with DSP0201.
Otherwise, the returned CIM-XML representation is a INSTANCEPATH element consistent with DSP0201.
The order of keybindings in the returned CIM-XML representation is preserved from the
CIMInstanceName
object.Parameters: Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None, ignore_host=False, ignore_namespace=False)[source]¶ Return the CIM-XML representation of this CIM instance path, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: - indent (string or integer) –
None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
- ignore_host (
bool
) – Ignore the host of the instance path, even if a host is specified. - ignore_namespace (
bool
) – Ignore the namespace and host of the instance path, even if a namespace and/or host is specified.
Returns: The CIM-XML representation of the value, as a unicode string.
- indent (string or integer) –
-
static
from_wbem_uri
(wbem_uri)[source]¶ Return a new
CIMInstanceName
object from the specified WBEM URI string.New in pywbem 0.12.
The WBEM URI string must be a CIM instance path in untyped WBEM URI format, as defined in DSP0207, with these extensions:
- DSP0207 restricts the namespace types (URI schemes) to be one
of
http
,https
,cimxml-wbem
, orcimxml-wbems
. Pywbem tolerates any namespace type, but issues aUserWarning
if it is not one of the namespace types defined in DSP0207. - DSP0207 requires a slash before the namespace name. For local WBEM URIs (no namespace type, no authority), that slash is the first character of the WBEM URI. For historical reasons, pywbem tolerates a missing leading slash for local WBEM URIs. Note that pywbem requires the slash (consistent with DSP0207) when the WBEM URI is not local.
- DSP0207 requires a colon before the class name. For historical reasons, pywbem tolerates a missing colon before the class name, if it would have been the first character of the string.
- DSP0207 requires datetime values in keybindings to be
surrounded by double quotes. For historical reasons, pywbem tolerates
datetime values that are not surrounded by double quotes, but issues
a
UserWarning
. - DSP0207 does not allow the special float values INF, -INF, and NaN in WBEM URIs (according to realValue in DSP0004). However, the CIM-XML protocol supports representation of these special values, so to be on the safe side, pywbem supports these special values as keybindings in WBEM URIs.
Keybindings that are references are supported, recursively.
CIM instance paths in the typed WBEM URI format defined in DSP0207 are not supported.
The untyped WBEM URI format defined in DSP0207 has the following limitations when interpreting a WBEM URI string:
- It cannot distinguish string-typed keys with a value that is a datetime value from datetime-typed keys with such a value. Pywbem treats such values as datetime-typed keys.
- It cannot distinguish string-typed keys with a value that is a WBEM URI from reference-typed keys with such a value. Pywbem treats such values as reference-typed keys.
Examples:
https://jdd:test@acme.com:5989/cimv2/test:CIM_RegisteredProfile.InstanceID="acme.1" //jdd:test@acme.com:5989/cimv2/test:CIM_RegisteredProfile.InstanceID="acme.1" /cimv2/test:CIM_RegisteredProfile.InstanceID="acme.1" cimv2/test:CIM_RegisteredProfile.InstanceID="acme.1" /:CIM_RegisteredProfile.InstanceID="acme.1" :CIM_RegisteredProfile.InstanceID="acme.1" CIM_RegisteredProfile.InstanceID="acme.1" http://acme.com/root/cimv2:CIM_ComputerSystem.CreationClassName="ACME_CS",Name="sys1" /:CIM_SubProfile.Main="/:CIM_RegisteredProfile.InstanceID="acme.1"",Sub="/:CIM_RegisteredProfile.InstanceID="acme.2""
Parameters: wbem_uri (string) – WBEM URI for an instance path. Returns: The instance path created from the specified WBEM URI string. Return type: CIMInstanceName
Raises: ValueError
– Invalid WBEM URI format for an instance path. This includes typed WBEM URIs.- DSP0207 restricts the namespace types (URI schemes) to be one
of
-
to_wbem_uri
(format='standard')[source]¶ Return the (untyped) WBEM URI string of this CIM instance path.
The returned WBEM URI contains its components as follows:
- it does not contain a namespace type (URI scheme).
- it contains an authority (host) component according to the
host
attribute, if that is not None. Otherwise, it does not contain the authority component. - it contains a namespace component according to the
namespace
attribute, if that is not None. Otherwise, it does not contain the namespace component. - it contains a class name component according to the
classname
attribute. - it contains keybindings according to the
keybindings
attribute, with the order of keybindings preserved, and the lexical case of keybinding names preserved (except when using the format “canonical”).
Note that when you do not want some of these components to show up in the resulting WBEM URI string, you can set them to None before calling this method.
Except when using the format “canonical”, this method should not be used to compare instance paths for equality: DSP0004 defines defines several components of an instance path to be compared case insensitively, including the names of keybindings. In addition, it defines that the order of keybindings in instance paths does not matter for the comparison. All WBEM URI formats returned by this method except for the format “canonical” return a WBEM URI string that preserves the order of keybindings (relative to how the keybindings were first added to the
CIMInstanceName
object) and that preserves the lexical case of any components. Therefore, two instance paths that are considered equal according to DSP0004 may not have equal WBEM URI strings as returned by this method.Instead, equality of instance paths represented by
CIMInstanceName
objects should be determined by using the==
operator, which performs the comparison conformant to DSP0004. If you have WBEM URI strings without the correspondingCIMInstanceName
object, such an object can be created by using the static methodfrom_wbem_uri()
.Parameters: format (string) – Format for the generated WBEM URI string, using one of the following values:
"standard"
- Standard format that is conformant to untyped WBEM URIs for instance paths defined in DSP0207."canonical"
- Like"standard"
, except that the following items have been converted to lower case: host, namespace, classname, and the names of any keybindings, and except that the order of keybindings is in lexical order of the (lower-cased) keybinding names. This format guarantees that two instance paths that are considered equal according to DSP0004 result in equal WBEM URI strings. Therefore, the returned WBEM URI is suitable to be used as a key in dictionaries of CIM instances."cimobject"
- Format for the CIMObject header field in CIM-XML messages for representing instance paths (used internally, see DSP0200)."historical"
- Historical format for WBEM URIs (used by__str__()
; should not be used by new code). The historical format has the following differences to the standard format:- If the host component is not present, the slash after the host is also omitted. In the standard format, that slash is always present.
- If the namespace component is not present, the colon after the namespace is also omitted. In the standard format, that colon is always present.
Keybindings that are references use the specified format recursively.
Examples:
With host and namespace, standard format:
//ACME.com/cimv2/Test:CIM_RegisteredProfile.InstanceID="Acme.1"
With host and namespace, canonical format:
//acme.com/cimv2/test:cim_registeredprofile.instanceid="Acme.1"
Without host but with namespace, standard format:
/cimv2/Test:CIM_RegisteredProfile.InstanceID="Acme.1"
Without host but with namespace, canonical format:
/cimv2/test:cim_registeredprofile.instanceid="Acme.1"
Without host and without namespace, standard format:
/:CIM_RegisteredProfile.InstanceID="Acme.1"
Returns: Untyped WBEM URI of the CIM instance path, in the specified format.
Return type: Raises: TypeError
– Invalid type in keybindingsValueError
– Invalid format
-
static
from_instance
(class_, instance, namespace=None, host=None, strict=False)[source]¶ Return a new
CIMInstanceName
object from the key property values in a CIM instance and the key property definitions in a CIM class.If the strict parameter is False, and a property value does not exist in the instance that entry is not included in the constructed CIMInstanceName
If the strict parameter is True all key properties in the class_ must exist in the instance or a ValueError exception is raised.
Parameters: - class_ (
CIMClass
) –The CIM class with the key properties.
In strict mode, that class and the instance must contain all key properties that are required to create the
CIMInstanceName
object. Thus, for example, if the class were retrieved from a server, generally, the LocalOnly parameter in the request should be False to assure that superclass properties are retrieved and IncludeQualifiers parameter should be set to True to assure that qualifiers are retrieved.In non-strict mode, that class and instance may have missing key properties. Any missing key properties will result in missing key bindings in the created
CIMInstanceName
object.The specified class does not need to be the creation class of the instance. Thus, it could be a superclass as long as it has the required key properties.
- instance (
CIMInstance
) – The CIM instance with the key property values. - namespace (string) – Namespace to include in the created
CIMInstanceName
or None. - host (string) – Host name to include in created
CIMInstanceName
or None. - strict (
bool
) – Strict mode (see description of class_ parameter).
Returns: CIMInstanceName
built from the key properties in the class_ parameter using the key property values in the instance parameter.Return type: Raises: ValueError
– The strict attribute is True and a key property does not exist in the instance.- class_ (
- classname (string) –
CIMInstance¶
-
class
pywbem.
CIMInstance
(classname, properties=None, qualifiers=None, path=None, property_list=None)[source]¶ A representation of a CIM instance in a CIM namespace in a WBEM server, optionally including its instance path.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
Parameters: - classname (string) –
Name of the creation class for the instance.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- properties (properties input object) –
The property values for the instance.
If the specified path has keybindings that correspond to these properties, the values of these keybindings will be updated to match the property values.
- qualifiers (qualifiers input object) –
The qualifiers for the instance.
Note that DSP0200 has deprecated the presence of qualifiers on CIM instances.
- path (
CIMInstanceName
) –Instance path for the instance.
The provided object will be copied before being stored in the
CIMInstance
object.If this path has keybindings that correspond to the specified properties, the values of the keybindings in (the copy of) this path will be updated to match the property values.
None means that the instance path is unspecified, and the
path
attribute will also be None. - property_list (iterable of string) –
Deprecated: List of property names for use as a filter by some operations on the instance.
This parameter has been deprecated in pywbem 0.12. Set only the desired properties on the object, instead of working with this property filter.
The property names may have any lexical case.
A copy of the provided iterable will be stored in the
CIMInstance
object, and the property names will be converted to lower case.None means that the properties are not filtered, and the
property_list
attribute will also be None.
Raises: ValueError
– classname is None, a property or qualifier name is None, or a property or qualifier name does not match its dictionary key.TypeError
– a numeric Python type was used for a property or qualifier value.
Methods
copy
Return a new CIMInstance
object that is a copy of this CIM instance.from_class
Return a new CIMInstance
object from specified key property values and from the key property definitions in a class.get
Return the value of a particular property of this CIM instance, or a default value. has_key
Return a boolean indicating whether this CIM instance has a particular property. items
Return a copied list of the property names and values of this CIM instance. iteritems
Iterate through the property names and values of this CIM instance. iterkeys
Iterate through the property names of this CIM instance. itervalues
Iterate through the property values of this CIM instance. keys
Return a copied list of the property names of this CIM instance. tocimxml
Return the CIM-XML representation of this CIM instance, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM instance, as a unicode string. tomof
Return a MOF string with the specification of this CIM instance. update
Update the properties of this CIM instance. update_existing
Update already existing properties of this CIM instance. values
Return a copied list of the property values of this CIM instance. Attributes
classname
Name of the creation class of this CIM instance. path
Instance path of this CIM instance. properties
Properties of this CIM instance. property_list
Deprecated: List of property names for use as a filter by some operations on this CIM instance. qualifiers
Qualifiers (qualifier values) of this CIM instance. Details
-
classname
¶ Name of the creation class of this CIM instance.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
properties
¶ Properties of this CIM instance.
Will not be None.
Each dictionary item specifies one property value, with:
- key (unicode string): Property name. Its lexical case was preserved.
- value (
CIMProperty
): Property value.
The order of properties in the CIM instance is preserved.
This attribute is settable; setting it will cause the current CIM properties to be replaced with the new properties, and will also cause the values of corresponding keybindings in the instance path (if set) to be updated. For details, see the description of the same-named init parameter. Note that the property value may be specified as a CIM data type or as a
CIMProperty
object.The CIM property values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. In that case, the provided input value must be a
CIMProperty
object. A corresponding keybinding in the instance path (if set) will not (!) be updated in this case:inst = CIMInstance(...) p1 = CIMProperty('p1', ...) # must be CIMProperty inst.properties['p1'] = p1 # Set "p1" to p1 (add if needed) p1 = inst.properties['p1'] # Access "p1" del inst.properties['p1'] # Delete "p1" from the instance
In addition, the CIM properties can be accessed and manipulated one by one by using the entire
CIMInstance
object like a dictionary. In that case, the provided input value may be specified as a CIM data type or as aCIMProperty
object. The value of a corresponding keybinding in the instance path (if set) will be updated to the new property value:inst = CIMInstance(...) p2 = Uint32(...) # may be CIM data type or CIMProperty inst['p2'] = p2 # Set "p2" to p2 (add if needed) p2 = inst['p2'] # Access "p2" del inst['p2'] # Delete "p2" from the instance
Type: NocaseDict
-
qualifiers
¶ Qualifiers (qualifier values) of this CIM instance.
Will not be None.
Each dictionary item specifies one qualifier value, with:
- key (unicode string): Qualifier name. Its lexical case was preserved.
- value (
CIMQualifier
): Qualifier value.
The order of qualifiers in the CIM instance is preserved.
This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of
this class
.The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
Type: NocaseDict
-
path
¶ Instance path of this CIM instance.
None means that the instance path is unspecified.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: CIMInstanceName
-
property_list
¶ Deprecated: List of property names for use as a filter by some operations on this CIM instance.
This attribute has been deprecated in pywbem 0.12. Set only the desired properties on the object, instead of working with this property filter.
The property names are specified in lower case.
None means that the properties are not filtered.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: list of unicode string
-
__str__
()[source]¶ Return a short string representation of this CIM instance, for human consumption.
-
__repr__
()[source]¶ Return a string representation of this CIM instance, that is suitable for debugging.
The properties and qualifiers will be ordered by their names in the result.
-
copy
()[source]¶ Return a new
CIMInstance
object that is a copy of this CIM instance.This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:
- The
CIMProperty
objects in theproperties
dictionary (but not the dictionary object itself) - The
CIMQualifier
objects in thequalifiers
dictionary (but not the dictionary object itself)
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.- The
-
update
(*args, **kwargs)[source]¶ Update the properties of this CIM instance.
Existing properties will be updated, and new properties will be added.
Parameters: - *args (list) – Properties for updating the properties of the instance, specified
as positional arguments. Each positional argument must be a tuple
(key, value), where key and value are described for setting the
properties
property. - **kwargs (dict) – Properties for updating the properties of the instance, specified
as keyword arguments. The name and value of the keyword arguments
are described as key and value for setting the
properties
property.
- *args (list) – Properties for updating the properties of the instance, specified
as positional arguments. Each positional argument must be a tuple
(key, value), where key and value are described for setting the
-
update_existing
(*args, **kwargs)[source]¶ Update already existing properties of this CIM instance.
Existing properties will be updated, and new properties will be ignored without further notice.
Parameters: - *args (list) – Properties for updating the properties of the instance, specified
as positional arguments. Each positional argument must be a tuple
(key, value), where key and value are described for setting the
properties
property. - **kwargs (dict) – Properties for updating the properties of the instance, specified
as keyword arguments. The name and value of the keyword arguments
are described as key and value for setting the
properties
property.
- *args (list) – Properties for updating the properties of the instance, specified
as positional arguments. Each positional argument must be a tuple
(key, value), where key and value are described for setting the
-
has_key
(key)[source]¶ Return a boolean indicating whether this CIM instance has a particular property.
Parameters: key (string) – Name of the property (in any lexical case). Returns: Boolean indicating whether the instance has the property. Return type: bool
-
get
(key, default=None)[source]¶ Return the value of a particular property of this CIM instance, or a default value.
New in pywbem 0.8.
Parameters: - key (string) – Name of the property (in any lexical case).
- default (CIM data type) – Default value that is returned if a property with the specified name does not exist in the instance.
Returns: Value of the property, or the default value.
Return type:
-
keys
()[source]¶ Return a copied list of the property names of this CIM instance.
The property names have their original lexical case.
The order of properties is preserved.
-
values
()[source]¶ Return a copied list of the property values of this CIM instance.
The order of properties is preserved.
-
items
()[source]¶ Return a copied list of the property names and values of this CIM instance.
Each item in the returned list is a tuple of property name (in the original lexical case) and property value.
The order of properties is preserved.
-
iterkeys
()[source]¶ Iterate through the property names of this CIM instance.
The property names have their original lexical case.
The order of properties is preserved.
-
itervalues
()[source]¶ Iterate through the property values of this CIM instance.
The order of properties is preserved.
-
iteritems
()[source]¶ Iterate through the property names and values of this CIM instance.
Each iteration item is a tuple of the property name (in the original lexical case) and the property value.
The order of properties is preserved.
-
tocimxml
(ignore_path=False)[source]¶ Return the CIM-XML representation of this CIM instance, as an object of an appropriate subclass of Element.
If the instance has no instance path specified or if ignore_path is True, the returned CIM-XML representation is an INSTANCE element consistent with DSP0201. This is the required element for representing embedded instances.
Otherwise, if the instance path of the instance has no namespace specified, the returned CIM-XML representation is an VALUE.NAMEDINSTANCE element consistent with DSP0201.
Otherwise, if the instance path of the instance has no host specified, the returned CIM-XML representation is a VALUE.OBJECTWITHLOCALPATH element consistent with DSP0201.
Otherwise, the returned CIM-XML representation is a VALUE.INSTANCEWITHPATH element consistent with DSP0201.
The order of properties and qualifiers in the returned CIM-XML representation is preserved from the
CIMInstance
object.Parameters: ignore_path ( bool
) – Ignore the path of the instance, even if a path is specified.Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None, ignore_path=False)[source]¶ Return the CIM-XML representation of this CIM instance, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: - indent (string or integer) –
None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
- ignore_path (
bool
) – Ignore the path of the instance, even if a path is specified.
Returns: The CIM-XML representation of the object, as a unicode string.
- indent (string or integer) –
-
tomof
(indent=0, maxline=80)[source]¶ Return a MOF string with the specification of this CIM instance.
The returned MOF string conforms to the
instanceDeclaration
ABNF rule defined in DSP0004, with the following limitations:- Pywbem does not support instance aliases, so the returned MOF string does not define an alias name for the instance.
- Even though pywbem supports qualifiers on
CIMInstance
objects, and onCIMProperty
objects that are used as property values within an instance, the returned MOF string does not contain any qualifier values on the instance or on its property values.
The order of properties and qualifiers is preserved.
Parameters: indent (integer) – This parameter has been deprecated in pywbem 0.12. A value other than 0 causes a deprecation warning to be issued. Otherwise, the parameter is ignored and the returned MOF instance specification is not indented. Returns: MOF string. Return type: unicode string
-
static
from_class
(klass, namespace=None, property_values=None, include_missing_properties=True, include_path=True, include_class_origin=False)[source]¶ Return a new
CIMInstance
object from specified key property values and from the key property definitions in a class.The properties in the returned instance do not have any qualifiers.
Parameters: - klass (
CIMClass
) – CIMClass from which the instance will be constructed. This class must include qualifiers and should include properties from any superclasses in the model insure it includes all properties that are to be built into the instance, in particular any key properties if the include+path parameter is True. Seefrom_class()
for further requirements on the class. - namespace (string) – Namespace to be included in the path component of the returned CIMInstance if include_path parameter is True.
- property_values (
dict
or NocaseDict) – Dictionary containing name/value pairs where the names are the names of properties in the class and the properties are the property values to be set into the instance properties. The values must match the type defined for the property in the class. If a property is in the property_values dictionary but not in the class a ValueError exception is raised. Not all properties in the class need to be defined in property_values. - include_missing_properties –
Determines if properties not in the property_values parameter are included in the instance.
If True all properties from the class are included in the new instance including those not defined in property_values parameter with with the default value defined in the class if one is defined, or otherwise None”.
If False only properties in the property_values parameter are included in the new instance.
Returns: A CIM instance created from klass and property_values parameters with the defined properties and optionally the path component set.
No qualifiers are included in the returned instance and the existence of the class origin attribute depends on the include_class_origin parameter.
All other attributes of each property are the same as the corresponding class property.
Return type: Raises: ValueError
– Conflicts between the class properties and- property_values parameter or the instance does
- not include all key properties defined in the class.
TypeError
– Mismatch between types of the property values in- property_values parameter and the property type in the
- corresponding class property
- klass (
- classname (string) –
CIMClassName¶
-
class
pywbem.
CIMClassName
(classname, host=None, namespace=None)[source]¶ A CIM class path (aka CIM class name).
A CIM class path references a CIM class in a CIM namespace in a WBEM server. Namespace and WBEM server may be unspecified.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
Parameters: - classname (string) –
Class name of the referenced class.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- host (string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced class.
The format of the string must be:
host[:port]
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986
with the extensions for zone identifiers as defined in
RFC6874, supporting
-
(minus) for the delimiter before the zone ID string, as an additional choice to%25
.
None means that the WBEM server is unspecified, and the
host
attribute will also be None.The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- namespace (string) –
Name of the CIM namespace containing the referenced class.
None means that the namespace is unspecified, and the
namespace
attribute will also be None.Leading and trailing slash characters will be stripped. The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
Raises: ValueError
– classname is None.Methods
copy
Return a new CIMClassName
object that is a copy of this CIM class path.from_wbem_uri
Return a new CIMClassName
object from the specified WBEM URI string.to_wbem_uri
Return the (untyped) WBEM URI string of this CIM class path. tocimxml
Return the CIM-XML representation of this CIM class path, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM class path, as a unicode string. Attributes
classname
Class name of this CIM class path, identifying the referenced class. host
Host and optionally port of this CIM class path, identifying the WBEM server of the referenced class. namespace
Namespace name of this CIM class path, identifying the namespace of the referenced class. Details
-
classname
¶ Class name of this CIM class path, identifying the referenced class.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
namespace
¶ Namespace name of this CIM class path, identifying the namespace of the referenced class.
None means that the namespace is unspecified.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
host
¶ Host and optionally port of this CIM class path, identifying the WBEM server of the referenced class.
For details about the string format, see the same-named init parameter of
this class
.None means that the host and port are unspecified.
This attribute is settable. For details, see the description of the same-named init parameter.
Type: unicode string
-
copy
()[source]¶ Return a new
CIMClassName
object that is a copy of this CIM class path.Objects of this class have no mutable types in any attributes, so modifications of the original object will not affect the returned copy, and vice versa.
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.
-
__str__
()[source]¶ Return a WBEM URI string of this CIM class path.
The returned WBEM URI string is in the historical format returned by
to_wbem_uri()
.For new code, it is recommended that the standard format is used; it is returned by
to_wbem_uri()
as the default format.If you want to access the class name, use the
classname
attribute, instead of relying on the coincidence that the historical format of a WBEM URI without host and namespace happens to be the class name.Examples (for the historical format):
With host and namespace:
//acme.com/cimv2/test:CIM_RegisteredProfile
Without host but with namespace:
cimv2/test:CIM_RegisteredProfile
Without host and without namespace:
CIM_RegisteredProfile
-
__repr__
()[source]¶ Return a string representation of this CIM class path, that is suitable for debugging.
-
tocimxml
(ignore_host=False, ignore_namespace=False)[source]¶ Return the CIM-XML representation of this CIM class path, as an object of an appropriate subclass of Element.
If the class path has no namespace specified or if ignore_namespace is True, the returned CIM-XML representation is a CLASSNAME element consistent with DSP0201.
Otherwise, if the class path has no host specified or if ignore_host is True, the returned CIM-XML representation is a LOCALCLASSPATH element consistent with DSP0201.
Otherwise, the returned CIM-XML representation is a CLASSPATH element consistent with DSP0201.
Parameters: Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None, ignore_host=False, ignore_namespace=False)[source]¶ Return the CIM-XML representation of this CIM class path, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: - indent (string or integer) –
None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
- ignore_host (
bool
) – Ignore the host of the class path, even if a host is specified. - ignore_namespace (
bool
) – Ignore the namespace and host of the class path, even if a namespace and/or host is specified.
Returns: The CIM-XML representation of the object, as a unicode string.
- indent (string or integer) –
-
static
from_wbem_uri
(wbem_uri)[source]¶ Return a new
CIMClassName
object from the specified WBEM URI string.New in pywbem 0.12.
The WBEM URI string must be a CIM class path in untyped WBEM URI format, as defined in DSP0207, with these extensions:
- DSP0207 restricts the namespace types (URI schemes) to be one
of
http
,https
,cimxml-wbem
, orcimxml-wbems
. Pywbem tolerates any namespace type, but issues aUserWarning
if it is not one of the namespace types defined in DSP0207. - DSP0207 requires a slash before the namespace name. For local WBEM URIs (no namespace type, no authority), that slash is the first character of the WBEM URI. For historical reasons, pywbem tolerates a missing leading slash for local WBEM URIs. Note that pywbem requires the slash (consistent with DSP0207) when the WBEM URI is not local.
- DSP0207 requires a colon before the class name. For historical reasons, pywbem tolerates a missing colon before the class name, if it would have been the first character of the string.
CIM class paths in the typed WBEM URI format defined in DSP0207 are not supported.
Examples:
https://jdd:test@acme.com:5989/cimv2/test:CIM_RegisteredProfile http://acme.com/root/cimv2:CIM_ComputerSystem http:/root/cimv2:CIM_ComputerSystem /root/cimv2:CIM_ComputerSystem root/cimv2:CIM_ComputerSystem /:CIM_ComputerSystem :CIM_ComputerSystem CIM_ComputerSystem
Parameters: wbem_uri (string) – WBEM URI for a class path. Returns: The class path created from the specified WBEM URI string. Return type: CIMClassName
Raises: ValueError
– Invalid WBEM URI format for a class path. This includes typed WBEM URIs.- DSP0207 restricts the namespace types (URI schemes) to be one
of
-
to_wbem_uri
(format='standard')[source]¶ Return the (untyped) WBEM URI string of this CIM class path.
The returned WBEM URI contains its components as follows:
- it does not contain a namespace type (URI scheme).
- it contains an authority (host) component according to the
host
attribute, if that is not None. Otherwise, it does not contain the authority component. - it contains a namespace component according to the
namespace
attribute, if that is not None. Otherwise, it does not contain the namespace component. - it contains a class name component according to the
classname
attribute.
Note that when you do not want some of these components to show up in the resulting WBEM URI string, you can set them to None before calling this method.
Except when using the format “canonical”, this method should not be used to compare class paths for equality: DSP0004 defines several components of a class path to be compared case insensitively. All WBEM URI formats returned by this method except for the format “canonical” return a WBEM URI string that preserves the lexical case of any components. Therefore, two class paths that are considered equal according to DSP0004 may not have equal WBEM URI strings as as returned by this method.
Instead, equality of class paths represented by
CIMClassName
objects should be determined by using the==
operator, which performs the comparison conformant to DSP0004. If you have WBEM URI strings without the correspondingCIMClassName
object, such an object can be created by using the static methodfrom_wbem_uri()
.Parameters: format (string) – Format for the generated WBEM URI string, using one of the following values:
"standard"
- Standard format that is conformant to untyped WBEM URIs for class paths defined in DSP0207."canonical"
- Like"standard"
, except that the following items have been converted to lower case: host, namespace, and classname. This format guarantees that two class paths that are considered equal according to DSP0004 result in equal WBEM URI strings. Therefore, the returned WBEM URI is suitable to be used as a key in dictionaries of CIM classes."cimobject"
- Format for the CIMObject header field in CIM-XML messages for representing class paths (used internally, see DSP0200)."historical"
- Historical format for WBEM URIs (used by__str__()
; should not be used by new code). The historical format has the following differences to the standard format:- If the host component is not present, the slash after the host is also omitted. In the standard format, that slash is always present.
- If the namespace component is not present, the colon after the namespace is also omitted. In the standard format, that colon is always present.
Examples:
With host and namespace, standard format:
//ACME.com/cimv2/Test:CIM_RegisteredProfile
With host and namespace, canonical format:
//acme.com/cimv2/test:cim_registeredprofile
Without host but with namespace, standard format:
/cimv2/Test:CIM_RegisteredProfile
Without host but with namespace, canonical format:
/cimv2/test:cim_registeredprofile
Without host and without namespace, standard format:
/:CIM_RegisteredProfile
Returns: Untyped WBEM URI of the CIM class path, in the specified format. Return type: unicode string Raises: ValueError
– Invalid format
- classname (string) –
CIMClass¶
-
class
pywbem.
CIMClass
(classname, properties=None, methods=None, superclass=None, qualifiers=None, path=None)[source]¶ A representation of a CIM class in a CIM namespace in a WBEM server, optionally including its class path.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
Parameters: - classname (string) –
Class name of the class.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- properties (properties input object) – The property declarations for the class.
- methods (methods input object) – The method declarations for the class.
- superclass (string) –
Name of the superclass for the class.
None means that the class is a top-level class, and the
superclass
attribute will also be None.The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- qualifiers (qualifiers input object) – The qualifiers for the class.
- path (
CIMClassName
) –Class path for the class.
New in pywbem 0.11.
The provided object will be copied before being stored in the
CIMClass
object.None means that the instance path is unspecified, and the
path
attribute will also be None.This parameter has been added in pywbem 0.11 as a convenience for the user in order so that
CIMClass
objects can be self-contained w.r.t. their class path.
Raises: ValueError
– classname is None, a property, method or qualifier name is None, or a property, method or qualifier name does not match its dictionary key.TypeError
– a numeric Python type was used for a qualifier value.
Methods
copy
Return a new CIMClass
object that is a copy of this CIM class.tocimxml
Return the CIM-XML representation of this CIM class, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM class, as a unicode string. tomof
Return a MOF string with the declaration of this CIM class. Attributes
classname
Class name of this CIM class. methods
Methods (declarations) of this CIM class. path
Class path of this CIM class. properties
Properties (declarations) of this CIM class. qualifiers
Qualifiers (qualifier values) of this CIM class. superclass
Class name of the superclass of this CIM class. Details
-
classname
¶ Class name of this CIM class.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
superclass
¶ Class name of the superclass of this CIM class.
None means that the class is a top-level class.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
properties
¶ Properties (declarations) of this CIM class.
Will not be None.
Each dictionary item specifies one property declaration, with:
- key (unicode string): Property name. Its lexical case was preserved.
- value (
CIMProperty
): Property declaration.
The order of properties in the CIM class is preserved.
This attribute is settable; setting it will cause the current CIM properties to be replaced with the new properties. For details, see the description of the same-named init parameter of
this class
.The CIM properties can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be a
CIMProperty
object:cls = CIMClass(...) p1 = CIMProperty('p1', ...) # must be a CIMProperty cls.properties['p1'] = p1 # Set "p1" to p1 (add if needed) p1 = cls.properties['p1'] # Access "p1" del cls.properties['p1'] # Delete "p1" from the class
Type: NocaseDict
-
methods
¶ Methods (declarations) of this CIM class.
Will not be None.
Each dictionary item specifies one method, with:
- key (unicode string): Method name. Its lexical case was preserved.
- value (
CIMMethod
): Method declaration.
The order of methods in the CIM class is preserved.
This attribute is settable; setting it will cause the current CIM methods to be replaced with the new methods. For details, see the description of the same-named init parameter of
this class
.The CIM methods can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be a
CIMMethod
object:cls = CIMClass(...) m1 = CIMMethod('m1', ...) # must be a CIMMethod cls.methods['m1'] = m1 # Set "m1" to m1 (add if needed) m1 = cls.methods['m1'] # Access "m1" del cls.methods['m1'] # Delete "m1" from the class
Type: NocaseDict
-
qualifiers
¶ Qualifiers (qualifier values) of this CIM class.
Will not be None.
Each dictionary item specifies one qualifier value, with:
- key (unicode string): Qualifier name. Its lexical case was preserved.
- value (
CIMQualifier
): Qualifier value.
The order of qualifiers in the CIM class is preserved.
This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of
this class
.The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a
CIMQualifier
object:cls = CIMClass(...) q1 = Uint32(...) # may be CIM data type or CIMQualifier cls.qualifiers['q1'] = q1 # Set "q1" to q1 (add if needed) q1 = cls.qualifiers['q1'] # Access "q1" del cls.qualifiers['q1'] # Delete "q1" from the class
Type: NocaseDict
-
path
¶ Class path of this CIM class.
New in pywbem 0.11.
None means that the class path is unspecified.
This attribute has been added in pywbem 0.11 as a convenience for the user in order so that
CIMClass
objects can be self-contained w.r.t. their class path.This attribute will be set in in any
CIMClass
objects returned byWBEMConnection
methods, based on information in the response from the WBEM server.This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: CIMClassName
-
__repr__
()[source]¶ Return a string representation of this CIM class, that is suitable for debugging.
The order of properties, method and qualifiers will be preserved in the result.
-
copy
()[source]¶ Return a new
CIMClass
object that is a copy of this CIM class.This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:
- The
CIMProperty
objects in theproperties
dictionary (but not the dictionary object itself) - The
CIMMethod
objects in themethods
dictionary (but not the dictionary object itself) - The
CIMQualifier
objects in thequalifiers
dictionary (but not the dictionary object itself)
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.- The
-
tocimxml
()[source]¶ Return the CIM-XML representation of this CIM class, as an object of an appropriate subclass of Element.
The returned CIM-XML representation is a CLASS element consistent with DSP0201. This is the required element for representing embedded classes.
If the class has a class path specified, it will be ignored.
The order of properties, methods, parameters, and qualifiers in the returned CIM-XML representation is preserved from the
CIMClass
object.Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of this CIM class, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(maxline=80)[source]¶ Return a MOF string with the declaration of this CIM class.
The returned MOF string conforms to the
classDeclaration
ABNF rule defined in DSP0004.The order of properties, methods, parameters, and qualifiers is preserved.
The
path
attribute of this object will not be included in the returned MOF string.Consistent with that, class path information is not included in the returned MOF string.
Returns: MOF string. Return type: unicode string
- classname (string) –
CIMProperty¶
-
class
pywbem.
CIMProperty
(name, value, type=None, class_origin=None, array_size=None, propagated=None, is_array=None, reference_class=None, qualifiers=None, embedded_object=None)[source]¶ A CIM property (value or declaration).
This object can be used in a
CIMInstance
object for representing a property value, or in aCIMClass
object for representing a property declaration.For property values in CIM instances:
- The value attribute is the actual value of the property.
- Qualifiers are not allowed.
For property declarations in CIM classes:
- The value attribute is the default value of the property declaration.
- Qualifiers are allowed.
Scalar (=non-array) properties may have a value of NULL (= None), any primitive CIM data type, reference type, and string type with embedded instance or embedded object.
Array properties may be Null or may have elements with a value of NULL, any primitive CIM data type, and string type with embedded instance or embedded object. Reference types are not allowed in property arrays in CIM, as per DSP0004.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
The init method infers optional parameters that are not specified (for example, it infers type from the Python type of value and other information). If the specified parameters are inconsistent, an exception is raised. If an optional parameter is needed for some reason, an exception is raised.
Parameters: - name (string) –
Name of the property.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- value (CIM data type or other suitable types) –
Value of the property.
The property value is interpreted as an actual property value when the CIM property is used in a CIM instance, and as default value when the CIM property is used in a CIM class.
None means that the property is Null, and the same-named attribute in the
CIMProperty
object will also be None.The specified value will be converted to a CIM data type using the rules documented in the description of
cimvalue()
, taking into account the type parameter. - type (string) –
Name of the CIM data type of the property (e.g.
"uint8"
).None will cause the type to be inferred from the value parameter, raising
ValueError
if it cannot be inferred (for example when value is None or a Python integer).ValueError
is raised if the type is not a valid CIM data type (see CIM data types). - class_origin (string) –
The CIM class origin of the property (the name of the most derived class that defines or overrides the property in the class hierarchy of the class owning the property).
None means that class origin information is not available, and
class_origin
attribute will also be None.The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- array_size (integer) –
The size of the array property, for fixed-size arrays.
None means that the array property has variable size, and
array_size
attribute will also be None. - propagated (
bool
) –If not None, specifies whether the property declaration has been propagated from a superclass, or the property value has been propagated from the creation class.
None means that propagation information is not available, and
propagated
attribute will also be None. - is_array (
bool
) –A boolean indicating whether the property is an array (True) or a scalar (False).
If None, the
is_array
attribute will be inferred from the value parameter. If the value parameter is None, a scalar is assumed. - reference_class (string) –
For reference properties, the name of the class referenced by the property, or None indicating that the referenced class is unspecified.
For non-reference properties, must be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
Note: Prior to pywbem 0.11, the corresponding attribute was inferred from the creation class name of a referenced instance. This was incorrect and has been fixed in pywbem 0.11.
- qualifiers (qualifiers input object) – The qualifiers for the property declaration. Has no meaning for property values.
- embedded_object (string) –
A string value indicating the kind of embedded object represented by the property value. Has no meaning for property declarations.
For details about the possible values, see the corresponding attribute.
None means that the value is unspecified, causing the same-named attribute in the
CIMProperty
object to be inferred. An exception is raised if it cannot be inferred.False means the property value is not an embedded object, and is stored as None.
Examples:
# a string property: CIMProperty("MyString", "abc") # a uint8 property: CIMProperty("MyNum", 42, "uint8") # a uint8 property: CIMProperty("MyNum", Uint8(42)) # a uint8 array property: CIMProperty("MyNumArray", [1, 2, 3], "uint8") # a reference property: CIMProperty("MyRef", CIMInstanceName("Foo")) # an embedded object property containing a class: CIMProperty("MyEmbObj", CIMClass("Foo")) # an embedded object property containing an instance: CIMProperty("MyEmbObj", CIMInstance("Foo"), embedded_object="object") # an embedded instance property: CIMProperty("MyEmbInst", CIMInstance("Foo")) # a string property that is Null: CIMProperty("MyString", None, "string") # a uint8 property that is Null: CIMProperty("MyNum", None, "uint8") # a reference property that is Null: CIMProperty("MyRef", None, "reference", reference_class="MyClass") # an embedded object property that is Null: CIMProperty("MyEmbObj", None, "string", embedded_object="object") # an embedded instance property that is Null: CIMProperty("MyEmbInst", None, "string", embedded_object="instance")
Methods
copy
Return a new CIMProperty
object that is a copy of this CIM property.tocimxml
Return the CIM-XML representation of this CIM property, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM property, as a unicode string. tomof
Return a MOF string with the declaration of this CIM property for use in a CIM class, or the specification of this CIM property for use in a CIM instance. Attributes
array_size
The size of the fixed-size array of this CIM property. class_origin
The class origin of this CIM property, identifying the most derived class that defines or overrides the property in the class hierarchy of the class owning the property. embedded_object
A string value indicating the kind of embedded object represented by this CIM property value. is_array
Boolean indicating that this CIM property is an array (as opposed to a scalar). name
Name of this CIM property. propagated
Boolean indicating that the property declaration has been propagated from a superclass, or that the property value has been propagated from the creation class. qualifiers
Qualifiers (qualifier values) of this CIM property declaration. reference_class
The name of the class referenced by this CIM reference property. type
Name of the CIM data type of this CIM property. value
Value of this CIM property. Details
-
name
¶ Name of this CIM property.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
value
¶ Value of this CIM property.
The property value is interpreted as an actual property value when this CIM property is used in a CIM instance, and as default value when this CIM property is used in a CIM class.
None means that the value is Null.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: CIM data type
-
type
¶ Name of the CIM data type of this CIM property.
Example:
"uint8"
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
reference_class
¶ The name of the class referenced by this CIM reference property.
Will be None for non-reference properties or if the referenced class is unspecified in reference properties.
Note that in CIM instances returned from a WBEM server, DSP0201 recommends this attribute not to be set. For CIM classes returned from a WBEM server, DSP0201 requires this attribute to be set.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
embedded_object
¶ A string value indicating the kind of embedded object represented by this CIM property value.
Has no meaning for CIM property declarations.
The following values are defined for this parameter:
"instance"
: The property is declared with theEmbeddedInstance
qualifier, indicating that the property value is an embedded instance of the class specified as the value of theEmbeddedInstance
qualifier. The property value must be aCIMInstance
object, or None."object"
: The property is declared with theEmbeddedObject
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 aCIMInstance
orCIMClass
object, or None.- None, for properties not representing embedded objects.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
is_array
¶ Boolean indicating that this CIM property is an array (as opposed to a scalar).
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
array_size
¶ The size of the fixed-size array of this CIM property.
None means that the array has variable size, or that the property is a scalar.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: integer
-
class_origin
¶ The class origin of this CIM property, identifying the most derived class that defines or overrides the property in the class hierarchy of the class owning the property.
None means that class origin information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
propagated
¶ Boolean indicating that the property declaration has been propagated from a superclass, or that the property value has been propagated from the creation class.
None means that propagation information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
qualifiers
¶ Qualifiers (qualifier values) of this CIM property declaration.
Will not be None.
Each dictionary item specifies one qualifier value, with:
- key (unicode string): Qualifier name. Its lexical case was preserved.
- value (
CIMQualifier
): Qualifier value.
The order of qualifiers in the property is preserved.
This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of
this class
.The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a
CIMQualifier
object:prop = CIMProperty(...) q1 = CIMQualifier('q1', ...) # may be CIM data type or CIMQualifier prop.qualifiers['q1'] = q1 # Set "q1" to q1 (add if needed) q1 = prop.qualifiers['q1'] # Access "q1" del prop.qualifiers['q1'] # Delete "q1" from the class
Type: NocaseDict
-
copy
()[source]¶ Return a new
CIMProperty
object that is a copy of this CIM property.This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:
- The
CIMQualifier
objects in thequalifiers
dictionary (but not the dictionary object itself)
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.- The
-
__str__
()[source]¶ Return a short string representation of this CIM property, for human consumption.
-
__repr__
()[source]¶ Return a string representation of this CIM property, that is suitable for debugging.
The order of qualifiers will be preserved in the result.
-
tocimxml
()[source]¶ Return the CIM-XML representation of this CIM property, as an object of an appropriate subclass of Element.
The returned CIM-XML representation is a PROPERTY, PROPERTY.REFERENCE, or PROPERTY.ARRAY element dependent on the property type, and consistent with DSP0201. Note that array properties cannot be of reference type.
The order of qualifiers in the returned CIM-XML representation is preserved from the
CIMProperty
object.Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of this CIM property, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(is_instance=True, indent=0, maxline=80, line_pos=0)[source]¶ Return a MOF string with the declaration of this CIM property for use in a CIM class, or the specification of this CIM property for use in a CIM instance.
New in pywbem 0.9.
Even though pywbem supports qualifiers on
CIMProperty
objects that are used as property values within an instance, the returned MOF string for property values in instances does not contain any qualifier values.The order of qualifiers is preserved.
Parameters: Returns: MOF string.
Return type:
CIMMethod¶
-
class
pywbem.
CIMMethod
(name=None, return_type=None, parameters=None, class_origin=None, propagated=None, qualifiers=None, methodname=None)[source]¶ A method (declaration) in a CIM class.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
The init method stores the input parameters as-is and does not infer unspecified parameters from the others (like
CIMProperty
does).Parameters: - name (string) –
Deprecated: Name of this CIM method (just the method name, without class name or parenthesis).
This argument has been named methodname before pywbem 0.9. Using methodname as a named argument still works, but has been deprecated in pywbem 0.9.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- return_type (string) –
Name of the CIM data type of the method return type (e.g.
"uint32"
).Must not be None or
"reference"
.ValueError
is raised if the type is None,"reference"
, or not a valid CIM data type (see CIM data types).Support for void return types: Pywbem also does not support void return types, consistent with the CIM architecture and MOF syntax (see DSP0004). Note that void return types could be represented in CIM-XML (see DSP0201).
Support for reference return types: Pywbem does not support reference return types of methods. The CIM architecture and MOF syntax support reference return types, and the CIM-XML protocol supports the invocation of methods with reference return types. However, CIM-XML does not support the representation of class declarations with methods that have reference return types.
Support for array return types: Pywbem does not support array return types of methods, consistent with the CIM architecture, MOF syntax and CIM-XML.
- parameters (parameters input object) – Parameter declarations for the method.
- class_origin (string) –
The CIM class origin of the method (the name of the most derived class that defines or overrides the method in the class hierarchy of the class owning the method).
None means that class origin information is not available, and the
class_origin
attribute will also be None.The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- propagated (
bool
) –If not None, specifies whether the method has been propagated from a superclass.
None means that propagation information is not available, and the the
propagated
attribute will also be None. - qualifiers (qualifiers input object) – The qualifiers for the method.
Methods
copy
Return a new CIMMethod
object that is a copy of this CIM method.tocimxml
Return the CIM-XML representation of this CIM method, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM method, as a unicode string. tomof
Return a MOF string with the declaration of this CIM method for use in a CIM class declaration. Attributes
class_origin
The class origin of this CIM method, identifying the most derived class that defines or overrides the method in the class hierarchy of the class owning the method. name
Name of this CIM method. parameters
Parameters of this CIM method. propagated
Boolean indicating that this CIM method has been propagated from a superclass. qualifiers
Qualifiers (qualifier values) of this CIM method. return_type
Name of the CIM data type of the return type of this CIM method. Details
-
name
¶ Name of this CIM method.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
return_type
¶ Name of the CIM data type of the return type of this CIM method.
Example:
"uint32"
Will not be None or
"reference"
.This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
class_origin
¶ The class origin of this CIM method, identifying the most derived class that defines or overrides the method in the class hierarchy of the class owning the method.
None means that class origin information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
propagated
¶ Boolean indicating that this CIM method has been propagated from a superclass.
None means that propagation information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
parameters
¶ Parameters of this CIM method.
Will not be None.
Each dictionary item specifies one parameter, with:
- key (unicode string): Parameter name. Its lexical case was preserved.
- value (
CIMParameter
): Parameter declaration.
The order of parameters in the method is preserved.
This attribute is settable; setting it will cause the current parameters to be replaced with the new parameters. For details, see the description of the same-named init parameter of
this class
.The parameters can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value must be a
CIMParameter
object:meth = CIMMethod(...) p1 = CIMParameter('p1', ...) # must be a CIMParameter meth.parameters['p1'] = p1 # Set "p1" to p1 (add if needed) p1 = meth.parameters['p1'] # Access "p1" del meth.parameters['p1'] # Delete "p1" from the class
Type: NocaseDict
-
qualifiers
¶ Qualifiers (qualifier values) of this CIM method.
Will not be None.
Each dictionary item specifies one qualifier value, with:
- key (unicode string): Qualifier name. Its lexical case was preserved.
- value (
CIMQualifier
): Qualifier value.
The order of qualifiers in the method is preserved.
This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of
this class
.The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a
CIMQualifier
object:meth = CIMMethod(...) q1 = "..." # may be CIM data type or CIMQualifier meth.qualifiers['q1'] = q1 # Set "q1" to q1 (add if needed) q1 = meth.qualifiers['q1'] # Access "q1" del meth.qualifiers['q1'] # Delete "q1" from the class
Type: NocaseDict
-
__repr__
()[source]¶ Return a string representation of this CIM method, that is suitable for debugging.
The order of parameters and qualifiers will be preserved in the result.
-
copy
()[source]¶ Return a new
CIMMethod
object that is a copy of this CIM method.This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:
- The
CIMParameter
objects in theparameters
dictionary (but not the dictionary object itself) - The
CIMQualifier
objects in thequalifiers
dictionary (but not the dictionary object itself)
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.- The
-
tocimxml
()[source]¶ Return the CIM-XML representation of this CIM method, as an object of an appropriate subclass of Element.
The returned CIM-XML representation is a METHOD element consistent with DSP0201.
The order of parameters and qualifiers in the returned CIM-XML representation is preserved from the
CIMMethod
object.Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of this CIM method, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(indent=0, maxline=80)[source]¶ Return a MOF string with the declaration of this CIM method for use in a CIM class declaration.
The order of parameters and qualifiers is preserved.
Parameters: indent (integer) – Number of spaces to indent each line of the returned string, counted in the line with the method name. Returns: MOF string. Return type: unicode string
- name (string) –
CIMParameter¶
-
class
pywbem.
CIMParameter
(name, type, reference_class=None, is_array=None, array_size=None, qualifiers=None, value=None, embedded_object=None)[source]¶ A CIM parameter (value or declaration).
This object can be used as parameter value in the
InvokeMethod()
operation, and as a parameter declaration in aCIMMethod
object.For parameter values in method invocations:
- The value attribute is the actual value of the parameter.
- Qualifiers are not allowed.
For parameter declarations in method declarations:
- The value attribute is ignored.
- Qualifiers are allowed.
Scalar (=non-array) parameters and items in array parameters may have a value of NULL (= None), any primitive CIM data type, reference type, or string type with embedded instance or embedded object.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
The init method stores the input parameters as-is and does not infer unspecified parameters from the others (like
CIMProperty
does).Parameters: - name (string) –
Name of this CIM parameter.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- type (string) –
Name of the CIM data type of this CIM parameter.
Example:
"uint8"
Must not be None.
ValueError
is raised if the type is None or not a valid CIM data type (see CIM data types). - reference_class (string) –
For reference parameters, the name of the class referenced by the parameter, or None indicating that the referenced class is unspecified.
For non-reference parameters, must be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- is_array (
bool
) –A boolean indicating whether the parameter is an array (True) or a scalar (False).
If None, the
is_array
attribute will be inferred from the value parameter. If the value parameter is None, a scalar is assumed. - array_size (integer) –
The size of the array parameter, for fixed-size arrays.
None means that the array parameter has variable size, and the
array_size
attribute will also be None. - qualifiers (qualifiers input object) – The qualifiers for the parameter.
- value –
The value of the CIM method parameter for the method invocation. Has no meaning for parameter declarations.
The specified value will be converted to a CIM data type using the rules documented in the description of
cimvalue()
, taking into account the type parameter. - embedded_object (string) –
A string value indicating the kind of embedded object represented by the parameter value (i.e. the value parameter). Has no meaning for parameter declarations.
For details about the possible values, see the corresponding attribute.
None means that the value is unspecified, causing the same-named attribute in the
CIMParameter
object to be inferred from the parameter value (i.e. the value parameter). An exception is raised if it cannot be inferred.False means the parameter value is not an embedded object, and is stored as None.
Methods
copy
Return a new CIMParameter
object that is a copy of this CIM parameter.tocimxml
Return the CIM-XML representation of this CIM parameter, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM parameter, as a unicode string. tomof
Return a MOF string with the declaration of this CIM parameter for use in a CIM method declaration. Attributes
array_size
The size of the fixed-size array of this CIM parameter. embedded_object
A string value indicating the kind of embedded object represented by this CIM parameter value. is_array
Boolean indicating that this CIM parameter is an array (as opposed to a scalar). name
Name of this CIM parameter. qualifiers
Qualifiers (qualifier values) of this CIM parameter. reference_class
The name of the class referenced by this CIM reference parameter. type
Name of the CIM data type of this CIM parameter. value
The value of this CIM parameter for the method invocation. Details
-
name
¶ Name of this CIM parameter.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
type
¶ Name of the CIM data type of this CIM parameter.
Example:
"uint8"
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
reference_class
¶ The name of the class referenced by this CIM reference parameter.
Will be None for non-reference parameters or if the referenced class is unspecified in reference parameters.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
is_array
¶ Boolean indicating that this CIM parameter is an array (as opposed to a scalar).
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
array_size
¶ The size of the fixed-size array of this CIM parameter.
None means that the array has variable size, or that the parameter is a scalar.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: integer
-
qualifiers
¶ Qualifiers (qualifier values) of this CIM parameter.
Will not be None.
Each dictionary item specifies one qualifier value, with:
- key (unicode string): Qualifier name. Its lexical case was preserved.
- value (
CIMQualifier
): Qualifier value.
The order of qualifiers in the parameter is preserved.
This attribute is settable; setting it will cause the current qualifiers to be replaced with the new qualifiers. For details, see the description of the same-named init parameter of
this class
.The qualifier values can also be accessed and manipulated one by one because the attribute value is a modifiable dictionary. The provided input value may be specified as a CIM data type or as a
CIMQualifier
object:parm = CIMParameter(...) q1 = True # may be CIM data type or CIMQualifier parm.qualifiers['q1'] = q1 # Set "q1" to q1 (add if needed) q1 = parm.qualifiers['q1'] # Access "q1" del parm.qualifiers['q1'] # Delete "q1" from the class
Type: NocaseDict
-
value
¶ The value of this CIM parameter for the method invocation.
Has no meaning for parameter declarations.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.
-
embedded_object
¶ A string value indicating the kind of embedded object represented by this CIM parameter value.
Has no meaning for CIM parameter declarations.
The following values are defined for this parameter:
"instance"
: The parameter is declared with theEmbeddedInstance
qualifier, indicating that the parameter value is an embedded instance of the class specified as the value of theEmbeddedInstance
qualifier. The property value must be aCIMInstance
object, or None."object"
: The parameter is declared with theEmbeddedObject
qualifier, indicating that the parameter value is an embedded object (instance or class) of which the class name is not known. The parameter value must be aCIMInstance
orCIMClass
object, or None.- None, for parameters not representing embedded objects.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
__str__
()[source]¶ Return a short string representation of this CIM parameter, for human consumption.
-
__repr__
()[source]¶ Return a string representation of this CIM parameter, that is suitable for debugging.
The order of qualifiers will be preserved in the result.
-
copy
()[source]¶ Return a new
CIMParameter
object that is a copy of this CIM parameter.This is a middle-deep copy; any mutable types in attributes except the following are copied, so besides these exceptions, modifications of the original object will not affect the returned copy, and vice versa. The following mutable types are not copied and are therefore shared between original and copy:
- The
CIMQualifier
objects in thequalifiers
dictionary (but not the dictionary object itself)
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.- The
-
tocimxml
(as_value=False)[source]¶ Return the CIM-XML representation of this CIM parameter, as an object of an appropriate subclass of Element.
The returned CIM-XML representation can be created either as a parameter declaration for use in a method declaration, or as a parameter value for use in a method invocation.
If a parameter value is to be returned, the returned CIM-XML representation is a PARAMVALUE element with child elements dependent on the parameter type, and consistent with DSP0201.
If a parameter declaration is to be returned, the returned CIM-XML representation is a PARAMETER, PARAMETER.REFERENCE, PARAMETER.ARRAY, or PARAMETER.REFARRAY element dependent on the parameter type, and consistent with DSP0201.
The order of qualifiers in the returned CIM-XML representation of a parameter declaration is preserved from the
CIMParameter
object.Parameters: as_value (bool) – If True, return the object as a parameter value. Otherwise, return the object as a parameter declaration. Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None, as_value=False)[source]¶ Return the CIM-XML representation of this CIM parameter, as a unicode string.
New in pywbem 0.9.
The returned CIM-XML representation can be created either as a parameter declaration for use in a method declaration, or as a parameter value for use in a method invocation.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: - indent (string or integer) –
None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
- as_value (bool) – If True, return the object as a parameter value. Otherwise, return the object as a parameter declaration.
Returns: The CIM-XML representation of the object, as a unicode string.
- indent (string or integer) –
-
tomof
(indent=0, maxline=80)[source]¶ Return a MOF string with the declaration of this CIM parameter for use in a CIM method declaration.
The object is always interpreted as a parameter declaration; so the
value
andembedded_object
attributes are ignored.The order of qualifiers is preserved.
Parameters: indent (integer) – Number of spaces to indent each line of the returned string, counted in the line with the parameter name. Returns: MOF string. Return type: unicode string
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, thepropagated
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, theCIMQualifier
objects for qualifier values that are specified in MOF represent the specified values, and theirpropagated
property is False. TheCIMQualifier
objects for qualifier values that are not specified in MOF represent the effective values, and theirpropagated
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
, andtranslatable
). If any of these flavor properties is not None, the qualifier value represented by theCIMQualifier
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 aCIMQualifierDeclaration
object.Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
The init method infers optional parameters that are not specified (for example, it infers type from the Python type of value and other information). If the specified parameters are inconsistent, an exception is raised. If an optional parameter is needed for some reason, an exception is raised.
Parameters: - name (string) –
Name of the qualifier.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- value (CIM data type or other suitable types) –
Value of the qualifier.
None means that the qualifier is Null, and the same-named attribute in the
CIMQualifier
object will also be None.The specified value will be converted to a CIM data type using the rules documented in the description of
cimvalue()
, taking into account the type parameter. - type (string) –
Name of the CIM data type of the qualifier (e.g.
"uint8"
).None will cause the type to be inferred from the value parameter, raising
ValueError
if it cannot be inferred (for example when value is None or a Python integer).ValueError
is raised if the type is not a valid CIM data type (see CIM data types). - propagated (
bool
) –If not None, specifies whether the qualifier value has been propagated from a superclass.
None means that this information is not available, and the
propagated
attribute will also be None. - overridable (
bool
) –If not None, specifies whether the qualifier value is overridable in subclasses.
None means that this information is not available, and the
overridable
attribute will also be None. - tosubclass (
bool
) –If not None, specifies whether the qualifier value propagates to subclasses.
None means that this information is not available, and the
tosubclass
attribute will also be None. - toinstance (
bool
) –If not None, specifies whether the qualifier value propagates to instances.
None means that this information is not available, and the
toinstance
attribute will also be None.Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
- translatable (
bool
) –If not None, specifies whether the qualifier is translatable.
None means that this information is not available, and the
translatable
attribute will also be None.
Examples:
# a string qualifier: CIMQualifier("MyString", "abc") # a uint8 qualifier: CIMQualifier("MyNum", 42, "uint8") # a uint8 qualifier: CIMQualifier("MyNum", Uint8(42)) # a uint8 array qualifier: CIMQualifier("MyNumArray", [1, 2, 3], "uint8") # a string qualifier that is Null: CIMQualifier("MyString", None, "string") # a uint8 qualifier that is Null: CIMQualifier("MyNum", None, "uint8")
Methods
copy
Return a new CIMQualifier
object that is a copy of this CIM qualifier.tocimxml
Return the CIM-XML representation of this CIM qualifier, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM qualifier, as a unicode string. tomof
Return a MOF string with the specification of this CIM qualifier as a qualifier value. Attributes
name
Name of this CIM qualifier. overridable
If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor. propagated
Boolean indicating that the qualifier value has been propagated from a superclass. toinstance
If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor. tosubclass
If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor. translatable
If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor. type
Name of the CIM data type of this CIM qualifier. value
Value of this CIM qualifier. Details
-
name
¶ Name of this CIM qualifier.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
type
¶ Name of the CIM data type of this CIM qualifier.
Example:
"uint8"
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
value
¶ Value of this CIM qualifier.
None means that the value is Null.
For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: CIM data type
-
propagated
¶ Boolean indicating that the qualifier value has been propagated from a superclass.
None means that propagation information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
tosubclass
¶ If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True, specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier values does not propagate to subclasses).
None means that this information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
toinstance
¶ If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True specifies the ToInstance flavor(the qualifier value propagates to instances. If False, specifies that qualifier values do not propagate to instances. There is no flavor corresponding to toinstance=False.
None means that this information is not available.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
overridable
¶ If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True, specifies the EnableOverride flavor(the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor(the qualifier value is not overridable in subclasses).
None means that this information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
translatable
¶ If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True, specifies the Translatable flavor (the qualifier is translatable); if False specifies that the qualfier is not translatable. There is no flavor corresponding to translatable=False.
None means that this information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
__str__
()[source]¶ Return a short string representation of this CIM qualifier, for human consumption.
-
__repr__
()[source]¶ Return a string representation of this CIM qualifier, that is suitable for debugging.
-
copy
()[source]¶ Return a new
CIMQualifier
object that is a copy of this CIM qualifier.Objects of this class have no mutable types in any attributes, so modifications of the original object will not affect the returned copy, and vice versa.
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.
-
tocimxml
()[source]¶ Return the CIM-XML representation of this CIM qualifier, as an object of an appropriate subclass of Element.
The returned CIM-XML representation is a QUALIFIER element consistent with DSP0201.
Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of this CIM qualifier, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(indent=3, maxline=80, line_pos=0)[source]¶ Return a MOF string with the specification of this CIM qualifier as a qualifier value.
The items of array values are tried to keep on the same line. If the generated line would exceed the maximum MOF line length, the value is split into multiple lines, on array item boundaries, and/or within long strings on word boundaries.
If a string value (of a scalar value, or of an array item) is split into multiple lines, the first line of the value is put onto a line on its own.
Parameters: indent (integer) – For a multi-line result, the number of spaces to indent each line except the first line (on which the qualifier name appears). For a single-line result, ignored. Returns: MOF string. Return type: unicode string
- name (string) –
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:Because None is allowed as a value for the flavors attributes in constructing a
CIMQualifierDeclaration
, the user must insure that any flavor which has the value None is set to its default value if required for subsequent processing.The pywbem MOF compiler supplies all of the flavor values so that those which were not specified in the MOF are set to the DMTF defined default values.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are unchanged-hashable, with the hash value being based on its public attributes. Therefore, objects of this class can be used as members in a set (or as dictionary keys) only during periods in which their public attributes remain unchanged.
Parameters: - name (string) –
Name of the qualifier.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
- type (string) –
Name of the CIM data type of the qualifier (e.g.
"uint8"
).Must not be None.
ValueError
is raised if the type is None or not a valid CIM data type (see CIM data types). - value (CIM data type or other suitable types) –
Default value of the qualifier.
None means a default value of Null, and the
value
attribute will also be None.The specified value will be converted to a CIM data type using the rules documented in the description of
cimvalue()
, taking into account the type parameter. - is_array (
bool
) –A boolean indicating whether the qualifier is an array (True) or a scalar (False).
If None, the
is_array
attribute will be inferred from the value parameter. If the value parameter is None, a scalar is assumed. - array_size (integer) –
The size of the array qualifier, for fixed-size arrays.
None means that the array qualifier has variable size, and the
array_size
attribute will also be None. - scopes (
dict
or NocaseDict) –Scopes of the qualifier.
A shallow copy of the provided dictionary will be stored in the
CIMQualifierDeclaration
object.Each dictionary item specifies one scope value, with:
- key (string): Scope name, in upper case.
Must not be None.
- value (
bool
): Scope value, specifying whether the qualifier has that scope (i.e. can be applied to a CIM element of that kind).
Valid scope names are “CLASS”, “ASSOCIATION”, “REFERENCE”, “PROPERTY”, “METHOD”, “PARAMETER”, “INDICATION”, and “ANY”.
None is interpreted as an empty set of scopes.
For details about the dictionary items, see the corresponding attribute.
- key (string): Scope name, in upper case.
- overridable (
bool
) –If not None, defines the flavor that defines whether the qualifier value is overridable in subclasses.
None means that this information is not available, and the
overridable
attribute will also be None. - tosubclass (
bool
) –If not None, specifies the flavor that defines whether the qualifier value propagates to subclasses.
None means that this information is not available, and the
tosubclass
attribute will also be None. - toinstance (
bool
) –If not None, specifies the flavor that defines whether the qualifier value propagates to instances.
None means that this information is not available, and the
toinstance
attribute will also be None.Note that DSP0200 has deprecated the presence of qualifier values on CIM instances and this flavor is not defined in DSP0004
- translatable (
bool
) –If not None, specifies the flavor that defines whether the qualifier is translatable.
None means that this information is not available, and the
translatable
attribute will also be None.
Methods
copy
Return a new CIMQualifierDeclaration
object that is a copy of this CIM qualifier type.tocimxml
Return the CIM-XML representation of this CIM qualifier type, as an object of an appropriate subclass of Element. tocimxmlstr
Return the CIM-XML representation of this CIM qualifier type, as a unicode string. tomof
Return a MOF string with the declaration of this CIM qualifier type. Attributes
array_size
The size of the fixed-size array of this CIM qualifier type. is_array
Boolean indicating that this CIM qualifier type is an array (as opposed to a scalar). name
Name of this CIM qualifier type. overridable
If True, specifies the EnableOverride flavor (the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor (the qualifier value is not overridable in subclasses). scopes
Scopes of this CIM qualifier type. toinstance
If True, specifies the ToInstance flavor. tosubclass
If True specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier value does not propagate to subclasses). translatable
If True, specifies the Translatable flavor. type
Name of the CIM data type of this CIM qualifier type. value
Default value of this CIM qualifier type. Details
-
name
¶ Name of this CIM qualifier type.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
type
¶ Name of the CIM data type of this CIM qualifier type.
Example:
"uint8"
.Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: unicode string
-
value
¶ Default value of this CIM qualifier type.
None means that the value is Null.
For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: CIM data type
-
is_array
¶ Boolean indicating that this CIM qualifier type is an array (as opposed to a scalar).
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
array_size
¶ The size of the fixed-size array of this CIM qualifier type.
None means that the array has variable size (or that the qualifier type is not an array).
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: integer
-
scopes
¶ Scopes of this CIM qualifier type.
Each dictionary item specifies one scope value, with:
- key (unicode string): Scope name, in upper case.
- value (
bool
): Scope value, specifying whether the qualifier has that scope (i.e. can be applied to a CIM element of that kind).
Valid scope names are “CLASS”, “ASSOCIATION”, “INDICATION”, “PROPERTY”, “REFERENCE”, “METHOD”, “PARAMETER”, and “ANY”.
Will not be None.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: NocaseDict
-
tosubclass
¶ If True specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier value does not propagate to subclasses).
None means that this information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
toinstance
¶ If True, specifies the ToInstance flavor. This flavor specifies that the qualifier value propagates to instances. If False, specifies that qualifier values do not propagate to instances. There is no flavor corresponding to toinstance=False.
None means that this information is not available.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
overridable
¶ If True, specifies the EnableOverride flavor (the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor (the qualifier value is not overridable in subclasses).
None means that this information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
translatable
¶ If True, specifies the Translatable flavor. This flavor specifies that the qualifier is translatable. If False, specifies that the qualfier is not translatable. There is no flavor corresponding to translatable=False.
None means that this information is not available.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: bool
-
__str__
()[source]¶ Return a short string representation of this CIM qualifier type, for human consumption.
-
__repr__
()[source]¶ Return a string representation of this CIM qualifier type, that is suitable for debugging.
The scopes will be ordered by their names in the result.
-
copy
()[source]¶ Return a new
CIMQualifierDeclaration
object that is a copy of this CIM qualifier type.Objects of this class have no mutable types in any attributes, so modifications of the original object will not affect the returned copy, and vice versa.
Note that the Python functions
copy.copy()
andcopy.deepcopy()
can be used to create completely shallow or completely deep copies of objects of this class.
-
tocimxml
()[source]¶ Return the CIM-XML representation of this CIM qualifier type, as an object of an appropriate subclass of Element.
The returned CIM-XML representation is a QUALIFIER.DECLARATION element consistent with DSP0201.
Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of this CIM qualifier type, as a unicode string.
New in pywbem 0.9.
For the returned CIM-XML representation, see
tocimxml()
.Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(maxline=80)[source]¶ Return a MOF string with the declaration of this CIM qualifier type.
The returned MOF string conforms to the
qualifierDeclaration
ABNF rule defined in DSP0004.Qualifier flavors are included in the returned MOF string only when the information is available (i.e. the value of the corresponding attribute is not None).
Because DSP0004 does not support instance qualifiers, and thus does not define a flavor keyword for the
toinstance
attribute, that flavor is not included in the returned MOF string.Returns: MOF string. Return type: unicode string
- name (string) –
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 |
The CIM NULL value is represented with Python None which can be used for any CIM typed value to represent NULL.
Note that init methods of pywbem classes that take CIM typed values as input
may support Python types in addition to those shown above. For example, the
CIMProperty
class represents property values of CIM datetime
type internally as CIMDateTime
objects, but its init method
accepts datetime.timedelta
objects, datetime.datetime
objects, string, in addition to
CIMDateTime
objects.
-
class
pywbem.
CIMType
[source]¶ Base type for all CIM data types defined in this package.
Methods
Attributes
cimtype
The name of the CIM datatype, as a string. Details
-
cimtype
= None¶ The name of the CIM datatype, as a string. See CIM data types for details.
-
-
class
pywbem.
CIMDateTime
(dtarg)[source]¶ A value of CIM data type datetime.
The object represents either a timezone-aware point in time, or a time interval.
Two objects of this class compare equal if their public attributes compare equal. Objects of this class are immutable and hashable, with the hash value being based on their public attributes.
Parameters: dtarg – The value from which the object is initialized, as one of the following types:
- A string object will be interpreted as CIM datetime format (see DSP0004) and will result in a point in time or a time interval. The use of asterisk characters in the value is supported according to the rules defined in DSP0004 (e.g. “20180911124613.128***:000”).
- A
datetime.datetime
object will result in a point in time. If thedatetime.datetime
object is timezone-aware (seeMinutesFromUTC
), the specified timezone will be used. Otherwise, a default timezone of UTC will be assumed. - A
datetime.timedelta
object will result in a time interval. - Another
CIMDateTime
object will be copied.
Methods
fromtimestamp
Factory method that returns a new CIMDateTime
object from a POSIX timestamp value and optional timezone information.get_local_utcoffset
Return the timezone offset of the current local timezone as +/- minutes from UTC. now
Factory method that returns a new CIMDateTime
object representing the current date and time.Attributes
cimtype
The name of the CIM datatype "datetime"
datetime
The point in time represented by this object, as a datetime.datetime
object.is_interval
A boolean indicating whether this object represents a time interval (True) or a point in time (False). minutes_from_utc
The timezone offset of this point in time object as +/- minutes from UTC. precision
Precision of the time interval or point in time represented by this object, if the datetime input string contained asterisk characters. timedelta
The time interval represented by this object, as a datetime.timedelta
object.Details
-
cimtype
= 'datetime'¶ The name of the CIM datatype
"datetime"
-
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.
-
precision
¶ Precision of the time interval or point in time represented by this object, if the datetime input string contained asterisk characters.
The precision is the 0-based index of the first asterisk character in the datetime input string, or None if there were no asterisk characters. For example, the precision of the timestamp value “201809121230**.******+000” is 12.
-
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.
-
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-awareCIMDateTime
type.They are also used to provide timezone information to
now()
andfromtimestamp()
Example:
from datetime import datetime from time import time import pywbem # Create a timezone-aware datetime object (for CEDT = UTC+2h), and # convert that to CIM datetime: dt = datetime(year=2016, month=3, day=31, hour=19, minute=30, second=40, microsecond=654321, tzinfo=pywbem.MinutesFromUTC(120)) cim_dt = pywbem.CIMDateTime(dt) # Convert a POSIX timestamp value to CIM datetime (for EST = UTC-5h): posix_ts = time() # seconds since the epoch, not timezone-aware cim_dt = pywbem.CIMDateTime.fromtimestamp(posix_ts, pywbem.MinutesFromUTC(-300))
Parameters: offset (integer) – Timezone offset to be represented in the CIM datetime value in +/- minutes from UTC.
This is the offset of local time to UTC (including DST offset), where a positive value indicates minutes east of UTC, and a negative value indicates minutes west of UTC.
Methods
dst
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 adatetime.timedelta
object.fromutc
datetime in UTC -> datetime in local time. tzname
datetime -> string name of time zone. utcoffset
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 adatetime.timedelta
object.Attributes
Details
-
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 adatetime.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 adatetime.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
andint
(for Python 3) orlong
(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 aValueError
. The enforcement of the valid value range can be disabled via the configuration variableENFORCE_INTEGER_RANGE
.Two objects of subclasses of this base class compare equal if their numeric values compare equal. Objects of this class are immutable and hashable, with the hash value being based on its numeric value.
Instances of subclasses of this class can be initialized with the usual input arguments supported by integer, for example:
>>> pywbem.Uint8(42) Uint8(cimtype='uint8', 42) >>> pywbem.Uint8('42') Uint8(cimtype='uint8', 42) >>> pywbem.Uint8('2A', 16) Uint8(cimtype='uint8', 42) >>> pywbem.Uint8('100', 16) Traceback (most recent call last): . . . ValueError: Integer value 256 is out of range for CIM datatype uint8 >>> pywbem.Uint8(100, 10) Traceback (most recent call last): . . . TypeError: int() can't convert non-string with explicit base
Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype, as a string. denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the integer, according to the capabilities of its CIM data type. minvalue
The minimum valid value for the integer, according to the capabilities of its CIM data type. numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
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.
-
-
class
pywbem.
Uint8
[source]¶ A value of CIM data type uint8. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'uint8'¶ The name of the CIM datatype
-
minvalue
= 0¶ The minimum valid value for the CIM datatype
-
maxvalue
= 255¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Sint8
[source]¶ A value of CIM data type sint8. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'sint8'¶ The name of the CIM datatype
-
minvalue
= -128¶ The minimum valid value for the CIM datatype
-
maxvalue
= 127¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Uint16
[source]¶ A value of CIM data type uint16. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'uint16'¶ The name of the CIM datatype
-
minvalue
= 0¶ The minimum valid value for the CIM datatype
-
maxvalue
= 65535¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Sint16
[source]¶ A value of CIM data type sint16. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'sint16'¶ The name of the CIM datatype
-
minvalue
= -32768¶ The minimum valid value for the CIM datatype
-
maxvalue
= 32767¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Uint32
[source]¶ A value of CIM data type uint32. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'uint32'¶ The name of the CIM datatype
-
minvalue
= 0¶ The minimum valid value for the CIM datatype
-
maxvalue
= 4294967295¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Sint32
[source]¶ A value of CIM data type sint32. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'sint32'¶ The name of the CIM datatype
-
minvalue
= -2147483648¶ The minimum valid value for the CIM datatype
-
maxvalue
= 2147483647¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Uint64
[source]¶ A value of CIM data type uint64. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'uint64'¶ The name of the CIM datatype
-
minvalue
= 0¶ The minimum valid value for the CIM datatype
-
maxvalue
= 18446744073709551615L¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
Sint64
[source]¶ A value of CIM data type sint64. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.Methods
bit_length
Number of bits necessary to represent self in binary. conjugate
Returns self, the complex conjugate of any long. Attributes
cimtype
The name of the CIM datatype denominator
the denominator of a rational number in lowest terms imag
the imaginary part of a complex number maxvalue
The maximum valid value for the CIM datatype minvalue
The minimum valid value for the CIM datatype numerator
the numerator of a rational number in lowest terms real
the real part of a complex number Details
-
cimtype
= 'sint64'¶ The name of the CIM datatype
-
minvalue
= -9223372036854775808L¶ The minimum valid value for the CIM datatype
-
maxvalue
= 9223372036854775807L¶ The maximum valid value for the CIM datatype
-
-
class
pywbem.
CIMFloat
[source]¶ Base type for real (floating point) CIM data types.
Two objects of subclasses of this base class compare equal if their numeric values compare equal. Objects of this class are immutable and hashable, with the hash value being based on its numeric value.
Note that equality comparison of floating point numbers in Python (and in almost any programming language) comes with some surprises. See “Floating Point Arithmetic: Issues and Limitations” for details, and specifically “Comparing Floating Point Numbers, 2012 Edition” on the topic of equality comparison. The same issues apply to hash values that are based on the numeric value of floating point numbers. Therefore, it is not recommended to perform equality comparison of objects of subclasses of this class, or to use them as dictionary keys or as members in sets.
Methods
as_integer_ratio
Return a pair of integers, whose ratio is exactly equal to the original float and with a positive denominator. conjugate
Return self, the complex conjugate of any float. fromhex
Create a floating-point number from a hexadecimal string. hex
Return a hexadecimal representation of a floating-point number. is_integer
Return True if the float is an integer. Attributes
cimtype
The name of the CIM datatype, as a string. imag
the imaginary part of a complex number real
the real part of a complex number Details
-
class
pywbem.
Real32
[source]¶ A value of CIM data type real32. Derived from
CIMFloat
.It is not recommended to perform equality comparison on objects of this class, or to use them as dictionary keys or as members in sets. See
CIMFloat
for details.Methods
as_integer_ratio
Return a pair of integers, whose ratio is exactly equal to the original float and with a positive denominator. conjugate
Return self, the complex conjugate of any float. fromhex
Create a floating-point number from a hexadecimal string. hex
Return a hexadecimal representation of a floating-point number. is_integer
Return True if the float is an integer. Attributes
cimtype
The name of the CIM datatype imag
the imaginary part of a complex number real
the real part of a complex number Details
-
cimtype
= 'real32'¶ The name of the CIM datatype
-
-
class
pywbem.
Real64
[source]¶ A value of CIM data type real64. Derived from
CIMFloat
.It is not recommended to perform equality comparison on objects of this class, or to use them as dictionary keys or as members in sets. See
CIMFloat
for details.Methods
as_integer_ratio
Return a pair of integers, whose ratio is exactly equal to the original float and with a positive denominator. conjugate
Return self, the complex conjugate of any float. fromhex
Create a floating-point number from a hexadecimal string. hex
Return a hexadecimal representation of a floating-point number. is_integer
Return True if the float is an integer. Attributes
cimtype
The name of the CIM datatype imag
the imaginary part of a complex number real
the real part of a complex number Details
-
cimtype
= 'real64'¶ The name of the CIM datatype
-
Conversion functions¶
This section describes conversion functions related to CIM objects and CIM data types:
Function | Purpose |
---|---|
tocimxml() |
Return the CIM-XML representation of a CIM object or CIM data typed value as an Element object. |
tocimxmlstr() |
Return the CIM-XML representation of a CIM object or CIM data typed value as a unicode string. |
tocimobj() |
Return a CIM data typed value from a Python
value. Deprecated: Use
cimvalue() instead. |
cimvalue() |
Return a CIM data typed value from a Python value. |
cimtype() |
Return the CIM data type name of a CIM data typed value. |
type_from_name() |
Return the Python type object for a CIM data type name. |
-
pywbem.
tocimxml
(value)[source]¶ Return the CIM-XML representation of the input object, as an object of an appropriate subclass of Element.
The returned CIM-XML representation is consistent with DSP0201.
Parameters: value (CIM object, CIM data type, number, datetime.datetime
, or tuple/list thereof) –The input object.
Specifying None has been deprecated in pywbem 0.12.
Returns: The CIM-XML representation, as an object of an appropriate subclass of Element.
-
pywbem.
tocimxmlstr
(value, indent=None)[source]¶ Return the CIM-XML representation of the CIM object or CIM data type, as a unicode string.
New in pywbem 0.9.
The returned CIM-XML representation is consistent with DSP0201.
Parameters: - value (CIM object or CIM data type or Element) – The CIM object or CIM data type to be converted to CIM-XML, or an Element object that already is the CIM-XML representation.
- indent (string or integer) –
None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the value, as a unicode string.
-
pywbem.
tocimobj
(type_, value)[source]¶ Deprecated: Return a CIM object representing the specified value and type.
This function has been deprecated in pywbem 0.13. Use
cimvalue()
instead.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
- string. The string must be
- If type_ specifies the CIM datetime data type:
- All input types of
CIMDateTime
- All input types of
- If type_ specifies the CIM reference data type:
Returns: A CIM data type object, representing the specified value and type.
Raises: ValueError
– Input cannot be converted to defined CIM value type, or invalid CIM data type name.- type_ (string) –
-
pywbem.
cimvalue
(value, type)[source]¶ Return a CIM data type representing the specified value in the specified CIM type.
New in pywbem 0.12.
This function guarantees that the returned object is a valid CIM data type. If the input parameters are not sufficient to construct a CIM data type, an exception is raised.
If the provided value is already a CIM data type (or None), the input value is returned.
Otherwise, the value is converted to a CIM data type as described below.
If the provided value is a list, a new list is returned with this function being invoked recursively on the items of the input list.
Embedded objects and embedded instances are not handled by this function.
Parameters: - type (string) –
The CIM data type name for the CIM object. See CIM data types for valid type names.
If value is a list, type must specify the CIM data type name of an item in the list.
- value (CIM data type and other suitable types) –
The value to be represented as a CIM object.
If None, the returned object will be None.
The following other suitable types are supported (in addition to the respective CIM data type):
- If type is
'string'
or'char16'
:- Objects of type byte string; they will be converted to unicode string.
- If type specifies one of the CIM integer data types (e.g.
'uint8'
): - If type specifies one of the CIM float data types (e.g.
'real32'
): - If type is
'boolean'
:- Any object. The value is converted to bool using the standard Python truth testing procedure.
- If type is
'datetime'
:- Any object supported as an init parameter for
CIMDateTime
.
- Any object supported as an init parameter for
- If type is
'reference'
:- string. The string must be an untyped WBEM URI representing an instance path (see DSP0207).
CIMInstanceName
. An instance path.CIMClassName
. A class path.
- If type is
Returns: A CIM data type object, representing the specified value and type.
Raises: ValueError
– An input parameter has an invalid value.TypeError
– An input parameter has an invalid Python type.
- type (string) –
-
pywbem.
cimtype
(obj)[source]¶ Return the CIM data type name of a CIM typed object, as a string.
For an array, the type is determined from the first array element (CIM arrays must be homogeneous w.r.t. the type of their elements). If the array is empty, that is not possible and
ValueError
is raised.Note that Python numbers are not valid input objects because determining their CIM data type (e.g.
Uint8
,Real32
) would require knowing the value range. Therefore,TypeError
is raised in this case.Parameters: obj (CIM data type) – The object whose CIM data type name is returned.
Returns: The CIM data type name of the object (e.g.
"uint8"
).Return type: Raises: TypeError
– The object does not have a valid CIM data type.ValueError
– Cannot determine CIM data type from an empty array.
-
pywbem.
type_from_name
(type_name)[source]¶ Return the Python type object for a given CIM data type name.
For example, type name
"uint8"
will return type objectUint8
.For CIM data type names
"string"
and"char16"
, the unicode string type is returned (Unicode strings are the preferred representation for these CIM data types).The returned type can be used as a constructor from a differently typed input value in many cases. Notable limitations are:
In Python 3, the
str
type is used to represent CIM string data types. When constructing such an object from a byte string, the resulting string is not a unicode-translated version of the byte string as one would assume (and as is the case in Python 2), but instead that results in a unicode string that is a repr() representation of the byte string:string_type = type_from_name('string') # str s1 = b'abc' s2 = string_type(s1) # results in u"b'abc'", and not in u"abc"
Use decode() and encode() for strings instead of type conversion syntax (in both Python 2 and 3, for consistency).
Parameters: type_name (string) – The simple (=non-array) CIM data type name (e.g. "uint8"
or"reference"
).Returns: The Python type object for the CIM data type (e.g. Uint8
orCIMInstanceName
).Raises: ValueError
– Unknown CIM data type name.
CIM status codes¶
This section defines constants for two areas:
- CIM status codes (the
CIM_ERR_*
symbols). They are for example stored inCIMError
exceptions. - Default CIM namespace
DEFAULT_NAMESPACE
. It is used as a default namespace for a connection (seeWBEMConnection
) when no namespace is provided for an operation.
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. New in pywbem 0.9.
-
pywbem.cim_constants.
CIM_ERR_INVALID_ENUMERATION_CONTEXT
= 21¶ The enumeration identified by the specified context cannot be found, is in a closed state, does not exist, or is otherwise invalid. New in pywbem 0.9.
-
pywbem.cim_constants.
CIM_ERR_INVALID_OPERATION_TIMEOUT
= 22¶ The specified operation timeout is not supported by the WBEM server. New in pywbem 0.9.
-
pywbem.cim_constants.
CIM_ERR_PULL_HAS_BEEN_ABANDONED
= 23¶ The pull operation has been abandoned due to execution of a concurrent CloseEnumeration operation on the same enumeration. New in pywbem 0.9.
-
pywbem.cim_constants.
CIM_ERR_PULL_CANNOT_BE_ABANDONED
= 24¶ The attempt to abandon a concurrent pull operation on the same enumeration failed. The concurrent pull operation proceeds normally. New in pywbem 0.9.
-
pywbem.cim_constants.
CIM_ERR_SERVER_LIMITS_EXCEEDED
= 27¶ The WBEM server has failed the operation based upon exceeding server limits. New in pywbem 0.9.
-
pywbem.cim_constants.
CIM_ERR_SERVER_IS_SHUTTING_DOWN
= 28¶ The WBEM server is shutting down and cannot process the operation. New in pywbem 0.9.
-
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
(*args, **kwargs)[source]¶ Base class for pywbem specific exceptions.
Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
-
conn_id
¶ Connection ID of the connection in whose context the error happened.
None if the error did not happen in context of any connection, or if the connection context was not known.
Type: connection id
-
conn_str
¶ String that identifies the connection in exception messages.
Type: unicode string
-
class
pywbem.
ConnectionError
(*args, **kwargs)[source]¶ This exception indicates a problem with the connection to the WBEM server. A retry may or may not succeed. Derived from
Error
.Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
-
class
pywbem.
AuthError
(*args, **kwargs)[source]¶ This exception indicates an authentication error with the WBEM server, either during TLS/SSL handshake, or during HTTP-level authentication. Derived from
Error
.Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
-
class
pywbem.
HTTPError
(status, reason, cimerror=None, cimdetails=None, conn_id=None)[source]¶ This exception indicates that the WBEM server returned an HTTP response with a bad HTTP status code. Derived from
Error
.The args instance variable is a tuple (status, reason, cimerror, cimdetails).
The message instance variable is not set.
Occurrence of this exception nearly always indicates an issue with the WBEM server.
Parameters: - status (integer) – HTTP status code (e.g. 500).
- reason (string) – HTTP reason phrase (e.g. “Internal Server Error”).
- cimerror (string) – Value of the CIMError HTTP header field, if present. None, otherwise.
- cimdetails (dict) –
Dictionary with CIMOM-specific header fields with details about the situation reported in the CIMError header field.
- Key: header field name (e.g. PGErrorDetail)
- Value: header field value (i.e. text message)
Passing None will result in an empty dictionary.
- conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
Variables: args – A tuple (status, reason, cimerror, cimdetails) set from the corresponding init arguments.
Methods
Attributes
args
cimdetails
CIMOM-specific details on the situation reported in the CIMError header field. cimerror
Value of CIMError HTTP header field in response, if present. conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
reason
HTTP reason phrase. status
HTTP status code. Details
-
status
¶ HTTP status code.
Example: 500
See RFC2616 for a list of HTTP status codes and reason phrases.
Type: integer
-
reason
¶ HTTP reason phrase.
Example: “Internal Server Error”
See RFC2616 for a list of HTTP status codes and reason phrases.
Type: string
-
class
pywbem.
TimeoutError
(*args, **kwargs)[source]¶ This exception indicates that the client timed out waiting for the WBEM server. Derived from
Error
.Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
-
class
pywbem.
ParseError
(message, conn_id=None)[source]¶ This exception indicates a parsing error with the CIM-XML operation response the pywbem client received, or with the CIM-XML indication request the pywbem listener received.
Derived from
Error
.This class supports attaching the CIM-XML request and response data in properties
request_data
andresponse_data
, respectively. When exceptions of this class are raised by pywbem, these properties will always be set.The CIM-XML response data is part of the str() representation of the exception.
This exception is a base class for two more specific exceptions:
CIMXMLParseError
- Issue at the CIM-XML level (e.g. NAME attribute missing on CLASS element)XMLParseError
- Issue at the XML level (e.g. ill-formed XML)
Occurrence of this exception nearly always indicates an issue with the WBEM server.
Parameters: - message (string) – Error message (will be put into args[0]).
- conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
request_data
CIM-XML request data (unformatted). response_data
CIM-XML response data (unformatted). Details
-
class
pywbem.
CIMXMLParseError
(message, conn_id=None)[source]¶ This exception indicates a specific kind of
ParseError
that is an issue at the CIM-XML level.Example: ‘NAME’ attribute missing on ‘CLASS’ element.
Occurrence of this exception nearly always indicates an issue with the WBEM server.
Parameters: - message (string) – Error message (will be put into args[0]).
- conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
request_data
CIM-XML request data (unformatted). response_data
CIM-XML response data (unformatted). Details
-
class
pywbem.
XMLParseError
(message, conn_id=None)[source]¶ This exception indicates a specific kind of
ParseError
that is an issue at the XML level.Example: Ill-formed XML.
Occurrence of this exception nearly always indicates an issue with the WBEM server.
Parameters: - message (string) – Error message (will be put into args[0]).
- conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
request_data
CIM-XML request data (unformatted). response_data
CIM-XML response data (unformatted). Details
-
class
pywbem.
CIMError
(status_code, status_description=None, instances=None, conn_id=None)[source]¶ This exception indicates that the WBEM server returned an error response with a CIM status code. Derived from
Error
.Accessing the CIM status code of a
CIMError
object:In Python 2, any
Exception
object can be accessed by index and slice and will delegate such access to itsargs
instance variable. In Python 3, that ability has been removed.In pywbem 0.9, the
status_code
andstatus_description
properties were added.Therefore, the following approach is not recommended, because it does not work on Python 3:
except CIMError as exc: status_code = exc[0]
The following approach works for pywbem 0.7 or newer:
except CIMError as exc: status_code = exc.args[0]
The following approach is recommended when using pywbem 0.9 or newer:
except CIMError as exc: status_code = exc.status_code
Parameters: - status_code (integer) – Numeric CIM status code.
- status_description (string) – CIM status description text returned by the server, representing a human readable message describing the error. None, if the server did not return a description text.
- instances (list of
CIMInstance
) – List of CIM instances returned by the WBEM server in the error response, that provide more details on the error. None if there are no such instances. - conn_id (connection id) – Connection ID of the connection in whose context the error happened. None if the error did not happen in context of any connection, or if the connection context was not known.
Variables: args – A tuple (status_code, status_description) set from the corresponding init arguments.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. instances
CIM instances returned by the WBEM server in the error response, that provide more details on the error. message
status_code
Numeric CIM status code. status_code_name
Symbolic name of the CIM status code. status_description
CIM status description text returned by the server, representing a human readable message describing the error. Details
-
status_code
¶ Numeric CIM status code.
New in pywbem 0.9.
Example: 5
See CIM status codes for constants defining the numeric CIM status code values.
Type: integer
-
status_code_name
¶ Symbolic name of the CIM status code.
Example: “CIM_ERR_INVALID_CLASS”
New in pywbem 0.9.
If the CIM status code is invalid, the string “Invalid status code <status_code>” is returned.
Type: string
-
status_description
¶ CIM status description text returned by the server, representing a human readable message describing the error.
New in pywbem 0.9.
Example: “The specified class does not exist.”
If the server did not return a description, a short default text for the CIM status code is returned. If the CIM status code is invalid, the string “Invalid status code <status_code>” is returned.
Type: string
-
instances
¶ CIM instances returned by the WBEM server in the error response, that provide more details on the error.
New in pywbem 0.13.
None if there are no such instances.
Type: List of CIMInstance
-
class
pywbem.
ModelError
(*args, **kwargs)[source]¶ This exception indicates an error with the model implemented by the WBEM server, that was detected by the pywbem client.
Examples are mismatches in data types of CIM elements (properties, methods, parameters) between classes and instances, CIM elements that appear in instances without being declared in classes, or violations of requirements defined in advertised management profiles.
Derived from
Error
.Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
Warnings¶
The following warnings are pywbem specific warnings that can be issued by the WBEM client library.
-
class
pywbem.
Warning
(*args, **kwargs)[source]¶ Base class for pywbem specific warnings.
Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
-
class
pywbem.
ToleratedServerIssueWarning
(*args, **kwargs)[source]¶ This warning indicates an issue with the WBEM server that has been tolerated by pywbem.
Parameters: - conn_id (connection id) – Must be a keyword argument. Connection ID of the connection in whose context the error happened. Omitted or None if the error did not happen in context of any connection, or if the connection context was not known.
- *args – Any other positional arguments are passed to
Exception
. - **kwargs – Any other keyword arguments are passed to
Exception
.
Methods
Attributes
args
conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. message
Details
WBEM operation statistics¶
New in pywbem 0.11 as experimental and finalized in 0.12.
Pywbem supports measuring the elapsed times of the WBEM operations that were performed in context of a connection, and maintaining a statistics over these times.
This capability is disabled by default and can be enabled in either of these ways:
- When creating a
WBEMConnection
object, via itsstats_enabled
argument. - After the
WBEMConnection
object has been created, by modifying itsstats_enabled
instance attribute.
The Statistics
class maintains statistics over the measured
elapsed times of the WBEM operations and is the interface for accessing the
statistics. The statistics of a WBEMConnection
object are
accessible via its statistics
instance
attribute.
The OperationStatistic
class is a helper class that contains
the actual measurement data for one operation name.
There will be one OperationStatistic
object each operation
name (see the table of WBEMConnection methods in the WBEM operations
section for the operation names).
The OperationStatistic
objects are under control of the
Statistics
class.
The statistics support maintains two kinds of times for each kind of WBEM operation:
Client times: The elapsed times for the WBEMConnection operation methods from call to return. This is measured in pywbem pretty close to the API the pywbem user is calling.
Server times: The elapsed times for processing the WBEM operations in the WBEM server from receiving the CIM-XML request message to sending back the CIM-XML response message. The server times are not measured by pywbem, but are taken from the WBEMServerResponseTime HTTP header field of a CIM-XML response, if present. See DSP0200 for a description of this header field.
The WBEMServerResponseTime HTTP header field is optionally implemented by WBEM servers. The following WBEM servers are known to implement this header field:
- OpenPegasus
The difference between client time and server time is the time spent in the pywbem client, plus the time spent on the network between client and server.
The statistics support also maintains the size of the HTTP body in the CIM-XML request and response messages, in Bytes.
These times and sizes are maintained as average, minimum and maximum values for each kind of operation in a connection.
Finally, the statistics support maintains the total count of operations and the count of operations that failed, for each kind of operation.
All data in the statistics applies to WBEM operations performed during periods of time where the statistics are enabled on a connection. Operations performed during periods of time where the statistics are disabled on a connection, are simply ignored in the statistics.
For the Iter methods of WBEMConnection (e.g.
IterEnumerateInstances()
), the WBEM operations
performed on behalf of them are subject of the statistics, but the Iter methods
themselves do not show up in the statistics.
The following example shows how statistics are enabled, and how statistics
values are accessed individually using the
get_op_statistic()
method:
conn = pywbem.WBEMConnection(..., stats_enabled=True)
# Perform some operations on this connection
insts_1 = conn.EnumerateInstances('CIM_Foo1', 'root/cimv2')
insts_2 = conn.EnumerateInstances('CIM_Foo2', 'root/cimv2')
insts_3 = conn.EnumerateInstances('CIM_Foo3', 'root/cimv2')
inst_paths_1 = conn.EnumerateInstanceNames('CIM_Foo1', 'root/cimv2')
# Access statistics values for EnumerateInstances
ei_stats = conn.statistics.get_op_statistic('EnumerateInstances')
ei_count = ei_stats.count
ei_avg_client_time = ei_stats.avg_time
ei_avg_server_time = ei_stats.avg_server_time
In the previous example, the values in ei_stats
are “live”, i.e. they
continue to be updated as operations are performed. If a snapshot is needed at
a certain point in time that remains unaffected by further operations, this can
be achieved using the snapshot()
method:
# Take snapshot and access statistics values for EnumerateInstances
stats_snapshot = dict(conn.statistics.snapshot())
ei_stats = stats_snapshot['EnumerateInstances']
ei_count = ei_stats.count
ei_avg_client_time = ei_stats.avg_time
ei_avg_server_time = ei_stats.avg_server_time
It is also possible to simply print the current statistics of a connection as a
formatted table, using the formatted()
method:
# Print statistics values for all operations
print(conn.statistics.formatted())
The output could look like this, if the WBEM server returns WBEM server response times:
Statistics (times in seconds, lengths in Bytes):
Count Excep ClientTime ServerTime RequestLen ReplyLen Operation
Cnt Avg Min Max Avg Min Max Avg Min Max Avg Min Max
3 0 0.234 0.100 0.401 0.204 0.080 0.361 1233 1000 1500 26667 20000 35000 EnumerateInstances
1 0 0.100 0.100 0.100 0.080 0.080 0.080 1200 1200 1200 22000 22000 22000 EnumerateInstanceNames
-
class
pywbem.
Statistics
(enable=False)[source]¶ New in pywbem 0.11 as experimental and finalized in 0.12.
The statistics of a connection, that captures and provides statistics data about the WBEM operations performed on the connection.
This class contains an operation statistic object (of class
OperationStatistic
) for each kind of WBEM operation.A
Statistics
object can be in a state of enabled or disabled. If enabled, it accumulates the elapsed times between subsequent calls to thestart_timer()
andstop_timer()
methods of classOperationStatistic
. If disabled, calls to these methods do not accumulate any time. Initially, the statistics container is disabled.The enablement state of the
Statistics
object is controlled by the statistics enablement state of the connection it belongs to (seepywbem.WBEMConnection.stats_enabled()
)Parameters: enable ( bool
) – Initial enablement status for this statistics container.Methods
disable
Disable the statistics container. enable
Enable the statistics container. formatted
Return a human readable string with the statistics for this container. get_op_statistic
Get the OperationStatistic
object for an operation name or create a new object if an object for that name does not exist.reset
Reset all statistics and clear any statistic names. snapshot
Return a snapshot of the time statistics of this container. start_timer
This method is called by pywbem to start the timer for a particular operation execution. Attributes
enabled
Indicates whether the statistics container is enabled. Details
-
enabled
¶ Indicates whether the statistics container is enabled.
-
start_timer
(name)[source]¶ This method is called by pywbem to start the timer for a particular operation execution. It returns the corresponding
OperationStatistic
object, creating one if needed.The timer is subsequently stopped by pywbem by calling the
stop_timer()
method on the returnedOperationStatistic
object.Parameters: name (string) – Name of the operation. Returns: The operation statistic for the specified name. If this statistics container is disabled, a dummy operation statistic object is returned. Return type: OperationStatistic
-
get_op_statistic
(name)[source]¶ Get the
OperationStatistic
object for an operation name or create a new object if an object for that name does not exist.Parameters: name (string) – Name of the operation. Returns: The operation statistic for the specified operation name. If this statistics container is disabled, a dummy operation statistic object is returned. Return type: OperationStatistic
-
snapshot
()[source]¶ Return a snapshot of the time statistics of this container.
The snapshot represents the statistics data at the time this method is called, and remains unchanged even if the statistics of this container continues to be updated.
Returns: A list of tuples (name, stats) with: - name (string): Name of the operation
- stats (
OperationStatistic
): Time statistics for the operation
-
formatted
()[source]¶ Return a human readable string with the statistics for this container. The operations are sorted by decreasing average time.
The three columns for ServerTime are included only if the WBEM server has returned WBEM server response times.
Example if statistics are enabled:
Statistics (times in seconds, lengths in Bytes): Count Excep ClientTime ServerTime RequestLen ReplyLen Operation Cnt Avg Min Max Avg Min Max Avg Min Max Avg Min Max 3 0 0.234 0.100 0.401 0.204 0.080 0.361 1233 1000 1500 26667 20000 35000 EnumerateInstances 1 0 0.100 0.100 0.100 0.080 0.080 0.080 1200 1200 1200 22000 22000 22000 EnumerateInstanceNames . . .
Example if statistics are disabled:
Statistics (times in seconds, lengths in Bytes): Disabled
-
-
class
pywbem.
OperationStatistic
(container, name)[source]¶ New in pywbem 0.11 as experimental and finalized in 0.12.
A statistics data keeper for the executions of all operations with the same operation name.
Objects of this class are created by the
Statistics
class and can be accessed by pywbem users through itsget_op_statistic()
andsnapshot()
methods.Parameters: - container (
Statistics
) – The statistics container that holds this operation statistic object. - name (string) – Name of the operation.
Methods
formatted
Return a formatted one-line string with the statistics values for the operation for which this statistics object maintains data. reset
Reset the statistics data for this object. start_timer
This is a low-level method that is called by pywbem at the begin of an operation. stop_timer
This is a low-level method is called by pywbem at the end of an operation. Attributes
avg_reply_len
The average size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes. avg_request_len
The average size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes. avg_server_time
The average elapsed server time for execution of the measured operations, in seconds. avg_time
The average elapsed client time for execution of the measured operations, in seconds. container
The statistics container that holds this statistics object. count
The number of measured operations. exception_count
The number of measured operations that resulted in an exception returned to the pywbem user (for example because a failure was indicated in the operation response of the WBEM server, or because pywbem itself detected a failure before sending the request or after receiving the response). max_reply_len
The maximum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes. max_request_len
The maximum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes. max_server_time
The maximum elapsed server time for execution of the measured operations, in seconds. max_time
The maximum elapsed client time for execution of the measured operations, in seconds. min_reply_len
The minimum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes. min_request_len
The minimum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes. min_server_time
The minimum elapsed server time for execution of the measured operations, in seconds. min_time
The minimum elapsed client time for execution of the measured operations, in seconds. name
Name of the operation for which this statistics object maintains data. stat_start_time
Point in time when the first statistic was taken since this object was either created or reset, in seconds since the epoch (for details, see time.time()
).Details
-
stat_start_time
¶ Point in time when the first statistic was taken since this object was either created or reset, in seconds since the epoch (for details, see
time.time()
).Type: float
-
container
¶ The statistics container that holds this statistics object.
Type: Statistics
-
exception_count
¶ The number of measured operations that resulted in an exception returned to the pywbem user (for example because a failure was indicated in the operation response of the WBEM server, or because pywbem itself detected a failure before sending the request or after receiving the response).
Type: integer
-
avg_time
¶ The average elapsed client time for execution of the measured operations, in seconds.
Type: float
-
min_time
¶ The minimum elapsed client time for execution of the measured operations, in seconds.
Type: float
-
max_time
¶ The maximum elapsed client time for execution of the measured operations, in seconds.
Type: float
-
avg_server_time
¶ The average elapsed server time for execution of the measured operations, in seconds.
This time is 0 if the WBEM server did not return the WBEM server response time.
Type: float
-
min_server_time
¶ The minimum elapsed server time for execution of the measured operations, in seconds.
This time is 0 if the WBEM server did not return the WBEM server response time.
Type: float
-
max_server_time
¶ The maximum elapsed server time for execution of the measured operations, in seconds.
This time is 0 if the WBEM server did not return the WBEM server response time.
Type: float
-
avg_request_len
¶ The average size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
Type: float
-
min_request_len
¶ The minimum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
Type: float
-
max_request_len
¶ The maximum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
Type: float
-
avg_reply_len
¶ The average size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
Type: float
-
min_reply_len
¶ The minimum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
Type: float
-
max_reply_len
¶ The maximum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
Type: float
-
start_timer
()[source]¶ This is a low-level method that is called by pywbem at the begin of an operation. It starts the measurement for that operation, if statistics is enabled for the connection.
A subsequent invocation of
stop_timer()
will complete the measurement for that operation and will update the statistics data.
-
stop_timer
(request_len, reply_len, server_time=None, exception=False)[source]¶ This is a low-level method is called by pywbem at the end of an operation. It completes the measurement for that operation by capturing the needed data, and updates the statistics data, if statistics is enabled for the connection.
Parameters: - request_len (integer) – Size of the HTTP body of the CIM-XML request message, in Bytes.
- reply_len (integer) – Size of the HTTP body of the CIM-XML response message, in Bytes.
- exception (
bool
) – Boolean that specifies whether an exception was raised while processing the operation. - server_time (
bool
) – Time in seconds that the server optionally returns to the client in the HTTP response defining the time from when the server received the request to when it started sending the response. If None, there is no time from the server.
Returns: The elapsed time for the operation that just ended, or None if the statistics container holding this object is not enabled.
Return type:
-
formatted
(include_server_time)[source]¶ Return a formatted one-line string with the statistics values for the operation for which this statistics object maintains data.
This is a low-level method that is called by
pywbem.Statistics.formatted()
.
- container (
WBEM operation logging¶
New in pywbem 0.11 and redesigned in pywbem 0.12. Finalized in pywbem 0.13.
Pywbem logging overview¶
The pywbem package implements selected logging using the Python
logging
facility.
This section describes logging for use of the pywbem package as a WBEM client.
Section Logging in the listener describes logging for use of the pywbem
package as a WBEM listener.
Pywbem logging is used to record information passing between the pywbem client and WBEM servers but not as a general recorder for errors, state, etc. within pywbem. In effect it is a trace tool. Pywbem errors are generally passed to the pywbem API user as Python exceptions rather than being recorded in a log by a pywbem logger.
Pywbem logging uses two Python Logger
objects which are
termed pywbem loggers:
- API logger (Python logger name: ‘pywbem.api’) - Logs API calls and returns,
for the
WBEMConnection
methods that drive WBEM operations (see WBEM operations). This logs the API parameters and results, including CIM objects/exceptions. It also logs the creation ofWBEMConnection
objects to capture connection information in order to determine the connection to which a particular log record belongs. - HTTP logger (Python logger name: ‘pywbem.http’) - Logs HTTP requests and responses between the pywbem client and WBEM server. This logs the HTTP request data and response data including HTTP headers and CIM-XML payload.
Pywbem uses the logging.DEBUG
logging level for both loggers.
Pywbem adds a null handler to the logger named ‘pywbem’, in order to prevent the “No handlers could be found for logger …” warning. This follows best practices recommended in Configuring logging for a library and in several articles, for example in this article. Because this warning is no longer issued on Python 3.4 and higher, pywbem adds a null handler only on Python 2.6 and 2.7.
Because pywbem logs only at the logging.DEBUG
logging level, these
log events will not be printed by the Python root logger by default, and
therefore it is not necessary that pywbem attaches a null handler to any of its
loggers.
There are two steps to setting up pywbem logging:
Configure Python logging parameters
Sets the Python logging parameters for a pywbem logger or its parent loggers, such as log handler, message format, and logging level.
This can be done with Python logging functions or with the functions described in Logging configuration functions.
Activate WBEM connection(s) for logging and set detail level
In order to save the cycles for capturing the possibly large amounts of data needed for creating the log records, pywbem logging is inactive by default. Logging can be activated for an existing WBEM connection, or for all subsequently created WBEM connections.
Because the pywbem loggers can generate large quantities of information, the user can control the quantity of information produced by each pywbem logger by setting a detail level for each logger when activating a WBEM connection for logging.
Activation and setting detail levels are pywbem features so it requires using the functions described in Logging configuration functions.
Logging configuration functions¶
The pywbem loggers may be configured and/or WBEM connections may be activated for logging through the following pywbem functions.
These functions are the only mechanism for setting the detail level of a pywbem logger and for activating WBEM connection(s) for logging.
configure_logger()
- Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level.configure_loggers_from_string()
- Configure the pywbem loggers and optionally activate WBEM connections for logging and setting a log detail level, from a log configuration string.This is most useful in defining the pywbem logging from a command line tool such as pywbemcli so the complete logger configuration can be compressed into a single command line string.
Logging configuration examples¶
Examples for using configure_logger()
for configuring pywbem loggers and
for activating WBEM connections for logging:
Example: Configure the ‘pywbem.api’ logger with detail level ‘summary’ and output to stderr, and activate all subsequently created WBEM connections for logging:
configure_logger('api', log_dest='stderr', detail_level='summary', connection=True) # All of the following connections will log to stderr with summary output: conn1 = WBEMConnection(...) conn2 = WBEMConnection(...)
Example: Configure all pywbem loggers with the default detail level (‘all’) and output to a file, and activate a single existing WBEM connection for logging:
conn = WBEMConnection(...) configure_logger('all', log_dest='file', log_filname='my_logfile.log', connection=conn)
Examples for configuring the pywbem loggers using Python logging methods, and using the pywbem logging configuration functions only for setting the detail level and for activating WBEM connections for logging:
Example: Configure the pywbem parent logger (named ‘pywbem’) for logging to a rotating file, configure both pywbem loggers for detail level ‘summary’, and activate all subsequent WBEM connections for logging:
import logging from logging.handlers import RotatingFileHandler logger = logging.getLogger('pywbem') handler = RotatingFileHandler("my_log.log", maxBytes=2000, backupCount=10) handler.setLevel(logging.DEBUG) formatter = logging.Formatter('%(asctime)s - %(name)s - %(message)s') handler.setFormatter(formatter) logger.addHandler(handler) # configure without setting log_dest configure_logger('api', detail_level='summary', connection=True) # All of the following connections will log using the rotating file handler: conn1 = WBEMConnection(...) conn2 = WBEMConnection(...)
Examples for using configure_loggers_from_string()
for configuring the
pywbem loggers and for activating WBEM connections for logging:
Example: Configure the ‘pywbem.api’ logger with detail level ‘summary’, output to stderr, and activate all subsequently created WBEM connections for logging:
configure_loggers_from_string('api=stderr:summary', connection=True) # All of the following connections will log: conn1 = WBEMConnection(...) conn2 = WBEMConnection(...)
Example: Configure both pywbem loggers with the default detail level (‘all’) and output to the file ‘my_log.log’, and activate a single existing WBEM connection object (conn) for logging:
conn = WBEMConnection(...) configure_loggers_from_string('all=file', log_filname='my_log.log', connection=conn)
Log records¶
The following is an example of log output with detail level ‘summary’, where ‘1-32073’ is the connection identifier:
2018-03-17 11:39:09,877-pywbem.api.1-32073-Connection:1-32073 WBEMConnection(url='http://localhost', creds=None, default_namespace='root/cimv2')
2018-03-17 11:41:13,176-pywbem.api.1-32073-Request:1-32073 EnumerateClasses(ClassName=None, DeepInheritance=None, IncludeClassOrigin=None, IncludeQualifiers=None, LocalOnly=None, namespace=None)
2018-03-17 11:41:13,635-pywbem.api.1-32073-Return:1-32073 EnumerateClasses(list of CIMClass; count=103)
The keywords in each log record (‘Connection’, ‘Request’, ‘Return’ or ‘Exception’) identify whether the log record is connection data, API/HTTP request data, API/HTTP response data, or API exception data.
The loggers that actually create the log records are children of the configured
pywbem loggers and are unique for each WBEMConnection
object.
Their logger names are created from the configured logger names by appending
the connection identifier (conn_id
).
Thus the names of the loggers that actually create the log records are of the
form: ‘pywbem.<api/http>.<conn_id>’.
WBEM operation recording¶
The WBEM client library API provides the possibility to record the WBEM operations that are executed on a connection. WBEM Operation recording uses the classes and subclasses defined in WBEM operation recorders.
This is disabled by default and can be enabled by adding recorders to a
WBEMConnection
object with the method
add_operation_recorder()
.
Typical usage scenarios for various operation recorders are the tracing of WBEM operations, tracing of interactions with a WBEM server, or the generation of test cases.
Please note that the method of activating operation recorders changed starting
with pywbem 0.11.0 and the addition of a second recorder. See
add_operation_recorder()
for more information.
This adds the recorder defined in the method call to a list of active recorders
in the WBEMConnection
object. All active recorders are called
for each WBEM operation on a connection.
A recorder can be be disabled with
disable()
method and enabled with
enable()
method.
The following example activates the TestClientRecorder
recorder for a connection:
conn = WBEMConnection(...)
# Add a TestClientRecorder to the connection
yamlfp = TestClientRecorder.open_file(self.yamlfile, 'a')
tc_recorder = TestClientRecorder(yamlfp)
conn.add_operation_recorder(tc_recorder)
# TestClientRecorder is now active and will record WBEM operations
# on that connection.
. . .
# Disable the TestClientRecorder
tc_recorder.disable()
Note that the LogOperationRecorder
is dealt with through
the logging functions described in WBEM operation logging, and should
not be added to a conneciton by pywbem users.
Activated recorders can be computing-wise expensive so it is best not to activate a recorder unless it is to be used for that specific WBEMConnection.
The enable()
and
disable()
methods simply set
flags to bypass creating the final recorder output so activating and disabling
is still more compute-wise expensive than not activating a recorder at all.
WBEM operation recorders¶
The WBEM client library API includes the abstract base class
BaseOperationRecorder
from which operation recorders can be
written that perform specific recording tasks.
Users can write their own operation recorder classes based upon the
abstract base class BaseOperationRecorder
.
The WBEM client library API provides the following operation recorder classes:
Class | Purpose |
---|---|
TestClientRecorder |
Generate test cases for the test_client unit test module. |
LogOperationRecorder |
Generate logs using the Python logging
facility for
WBEMConnection
methods that communicate with a
WBEM server. |
-
class
pywbem.
BaseOperationRecorder
[source]¶ Abstract base class defining the interface to an operation recorder, that records the WBEM operations executed in a connection to a WBEM server.
Experimental: New in pywbem 0.9 as experimental.
An operation recorder can be added to a connection via the
add_operation_recorder()
method. The operation recorders of a connection can be retrieved via theoperation_recorders
property.Each operation that is executed on a connection will cause the
record()
method of those operation recorders of the connection to be called, that are enabled.After being added to a connection, an operation recorder is enabled. It can be disabled and re-enabled using the
disable()
andenable()
methods, respectively. This can be used to temporarily pause the recorder.Methods
disable
Disable the recorder. enable
Enable the recorder. open_file
A static convenience function that performs the open of the recorder file correctly for different versions of Python. record
Function that is called to record a single WBEM operation, i.e. record_staged
Encode staged information on request and result to output reset
Reset all the attributes in the class. stage_http_request
Set request HTTP information including url, headers, etc. stage_http_response1
Set response http info including headers, status, etc. stage_http_response2
Stage second part of http response, the payload stage_pywbem_args
Set requst method and all args. stage_pywbem_result
Set Result return info or exception info stage_wbem_connection
Stage information about the connection. Attributes
enabled
Indicate whether the recorder is enabled. Details
-
enabled
¶ Indicate whether the recorder is enabled.
New in pywbem 0.10.
-
static
open_file
(filename, file_mode='w')[source]¶ A static convenience function that performs the open of the recorder file correctly for different versions of Python.
New in pywbem 0.10.
This covers the issue where the file should be opened in text mode but that is done differently in Python 2 and Python 3.
The returned file-like object must be closed by the caller.
Parameters: Returns: File-like object.
Example:
recorder = TestClientRecorder(...) recorder_file = recorder.open_file('recorder.log') . . . # Perform WBEM operations using the recorder recorder_file.close()
-
reset
(pull_op=None)[source]¶ Reset all the attributes in the class. This also allows setting the pull_op attribute that defines whether the operation is to be a traditional or pull operation. This does NOT reset _conn.id as that exists through the life of the connection.
-
stage_wbem_connection
(wbem_connection)[source]¶ Stage information about the connection. Used only by LogOperationRecorder.
-
stage_pywbem_args
(method, **kwargs)[source]¶ Set requst method and all args. Normally called before the cmd is executed to record request parameters
-
stage_http_request
(conn_id, version, url, target, method, headers, payload)[source]¶ Set request HTTP information including url, headers, etc.
-
stage_http_response1
(conn_id, version, status, reason, headers)[source]¶ Set response http info including headers, status, etc. conn_id unused here. Used in log
-
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 theWBEMConnection
method that is recorded. - pywbem_result (
OpResult
) – The result (return value or exception) of theWBEMConnection
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).
- pywbem_args (
-
-
class
pywbem.
OpArgs
[source]¶ A named tuple representing the name and input arguments of the invocation of a
WBEMConnection
method.Experimental: New in pywbem 0.9 as experimental.
Variables: - method (unicode string) – Name of the
WBEMConnection
method. - args (
dict
) – Dictionary of input arguments (both positional and keyword-based).
Create new instance of OpArgsTuple(method, args)
- method (unicode string) – Name of the
-
class
pywbem.
OpResult
[source]¶ A named tuple representing the result of the invocation of a
WBEMConnection
method.Experimental: New in pywbem 0.9 as experimental.
Variables: - ret (
object
) –Return value, if the method returned. None, if the method raised an exception.
Note that None may be a legitimate return value, so the test for exceptions should be done based upon the
exc
variable. - exc (
Exception
) – Exception object, if the method raised an exception. None, if the method returned.
Create new instance of OpResultTuple(ret, exc)
- ret (
-
class
pywbem.
HttpRequest
[source]¶ A named tuple representing the HTTP request sent by the WBEM client.
Experimental: New in pywbem 0.9 as experimental.
Variables: - version (number) – HTTP version from the request line (10 for HTTP/1.0, 11 for HTTP/1.1).
- url (unicode string) – URL of the WBEM server (e.g. ‘https://myserver.acme.com:15989’).
- target (unicode string) – Target URL segment as stated in request line (e.g. ‘/cimom’).
- method (unicode string) – HTTP method as stated in the request line (e.g. “POST”).
- headers (
dict
) –A dictionary of all HTTP header fields:
- key (unicode string): Name of the header field
- value (unicode string): Value of the header field
- payload (unicode string) – HTTP payload, i.e. the CIM-XML string.
Create new instance of HttpRequestTuple(version, url, target, method, headers, payload)
-
class
pywbem.
HttpResponse
[source]¶ A named tuple representing the HTTP response received by the WBEM client.
Experimental: New in pywbem 0.9 as experimental.
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:
- key (unicode string): Name of the header field
- value (unicode string): Value of the header field
- payload (unicode string) – HTTP payload, i.e. the CIM-XML string.
Create new instance of HttpResponseTuple(version, status, reason, headers, payload)
-
class
pywbem.
TestClientRecorder
(fp)[source]¶ An operation recorder that generates test cases for each recorded operation.
Experimental: New in pywbem 0.9 as experimental.
The test cases are in the YAML format suitable for the test_client unit test module of the pywbem project.
Parameters: fp (file) – An open file that each test case will be written to. This file should have been opened in text mode.
Since there are differences between python 2 and 3 in opening files in text mode, the static method
open_file()
can be used to open the file or python 2/3 compatible open:from io import open f = open('blah.log', encoding='utf-8')
Example:
recorder = TestClientRecorder( BaseOperationRecorder.open_file('recorder.log'))
Methods
disable
Disable the recorder. enable
Enable the recorder. open_file
A static convenience function that performs the open of the recorder file correctly for different versions of Python. record
Function that records the invocation of a single WBEMConnection
method, by appending a corresponding test case to the file.record_staged
Encode staged information on request and result to output reset
Reset all the attributes in the class. stage_http_request
Set request HTTP information including url, headers, etc. stage_http_response1
Set response http info including headers, status, etc. stage_http_response2
Stage second part of http response, the payload stage_pywbem_args
Set requst method and all args. stage_pywbem_result
Set Result return info or exception info stage_wbem_connection
Stage information about the connection. toyaml
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. Attributes
EXCLUDE_REQUEST_HEADERS
EXCLUDE_RESPONSE_HEADERS
TESTCASE_PASSWORD
TESTCASE_URL
TESTCASE_USER
enabled
Indicate whether the recorder is enabled. Details
-
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()
.
-
-
class
pywbem.
LogOperationRecorder
(conn_id, detail_levels=None)[source]¶ A recorder that logs certain aspects of the WBEM operations driven by pywbem users to Python loggers.
Experimental: New in pywbem 0.11 and redesigned in pywbem 0.12 as experimental.
This recorder supports two Python loggers:
- API logger (Python logger name: ‘pywbem.api’) - Logs API calls and
returns, for the
WBEMConnection
methods that drive WBEM operations (see WBEM operations). This logs the API parameters and results, including CIM objects/exceptions. It also logs the creation ofWBEMConnection
objects to capture connection information in order to determine the connection to which a particular log record belongs. - HTTP logger (Python logger name: ‘pywbem.http’) - Logs HTTP requests and responses between the pywbem client and WBEM server. This logs the HTTP request data and response data including HTTP headers and CIM-XML payload.
All logging calls are at the
logging.DEBUG
logging level.Parameters: - conn_id (connection id) – String that represents an id for a particular connection that is used to build the name of each logger. The logger names are uniqueqly idenfified by the conn_id suffix to the logger name (ex.pywbem.ops.1-2343) so that each WBEMConnection could be logged with a separate logger.
- detail_levels (
dict
) – Dictionary identifying the detail level for one or both of the loggers. Key: Simple logger name (e.g. ‘api’). Value: Detail level, either a string fromLOG_DETAIL_LEVELS
, or an integer that specifies the maximum size of each log record.
Methods
disable
Disable the recorder. enable
Enable the recorder. open_file
A static convenience function that performs the open of the recorder file correctly for different versions of Python. record
Not used for logging record_staged
Not used for logging. reset
Reset all the attributes in the class. set_detail_level
Sets the detail levels from the input dictionary in detail_levels. stage_http_request
Log request HTTP information including url, headers, etc. stage_http_response1
Set response http info including headers, status, etc. stage_http_response2
Log complete http response, including response1 and payload stage_pywbem_args
Log request method and all args. stage_pywbem_result
Log result return or exception parameter. stage_wbem_connection
Log connection information. Attributes
enabled
Indicate whether the recorder is enabled. Details
-
set_detail_level
(detail_levels)[source]¶ Sets the detail levels from the input dictionary in detail_levels.
-
stage_wbem_connection
(wbem_connection)[source]¶ Log connection information. This includes the connection id (conn_id) that is output with the log entry. This entry is logged if either http or api loggers are enable. It honors both the logger and detail level of either api logger if defined or http logger if defined. If the api logger does not exist, the output shows this as an http loggger output since we do not want to create an api logger for this specific output
-
stage_pywbem_args
(method, **kwargs)[source]¶ Log request method and all args. Normally called before the cmd is executed to record request parameters. This method does not support the summary detail_level because that seems to add little info to the log that is not also in the response.
-
stage_pywbem_result
(ret, exc)[source]¶ Log result return or exception parameter. This method provides varied type of formatting based on the detail_level parameter and the data in ret.
-
stage_http_request
(conn_id, version, url, target, method, headers, payload)[source]¶ Log request HTTP information including url, headers, etc.
-
stage_http_response1
(conn_id, version, status, reason, headers)[source]¶ Set response http info including headers, status, etc.
- API logger (Python logger name: ‘pywbem.api’) - Logs API calls and
returns, for the
Mapping between ValueMap and Values qualifiers¶
The ValueMapping
class supports translating between the values
of an integer-typed CIM element (e.g. property, method, or parameter) that is
qualified with the ValueMap and Values qualifiers, and the corresponding
values of the Values qualifier, in both directions.
This class supports value ranges (e.g. "4..6"
) and the unclaimed marker
(".."
).
-
class
pywbem.
ValueMapping
[source]¶ New in pywbem 0.9 as experimental and finalized in 0.10.
A utility class that supports translating between the values of an integer-typed CIM element (property, method, parameter) that is qualified with the ValueMap and Values qualifiers, and the corresponding values of the Values qualifier, in both directions.
This is done by retrieving the CIM class definition defining the CIM element in question, and by inspecting its ValueMap and Values qualifiers.
The translation is performed by the
tovalues()
andtobinary()
methods.Instances of this class must be created through one of the factory class methods:
for_property()
,for_method()
, orfor_parameter()
.Value ranges (
"2..4"
) and the indicator for unclaimed values (".."
) in the ValueMap qualifier are supported.All representations of the integer values in the ValueMap qualifier are supported (decimal, binary, octal, hexadecimal), consistent with the definition of the ValueMap qualifier in DSP0004.
Example
Given the following definition of a property in MOF:
class CIM_Foo { [ValueMap{ "0", "2..4", "..6", "7..", "9", ".." }, Values{ "zero", "two-four", "five-six", "seven-eight", "nine", "unclaimed"}] uint16 MyProp; };
Assuming this class exists in a WBEM server, the following code will get the class from the server, create a value mapping for this property, and look up the Values strings that correspond to binary property values. This is useful when preparing binary property values for human consumption:
namespace = 'root/cimv2' conn = pywbem.WBEMConnection(...) # WBEM server myprop_vm = pywbem.ValueMapping.for_property( conn, namespace, 'CIM_Foo', 'MyProp') print("Binary value: Values string") for bin_value in range(0, 12): values_str = myprop_vm.tovalues(bin_value) print("{0:12}: {1!r}".format(bin_value, values_str))
Resulting output:
Binary value: Values string 0: 'zero' 1: 'unclaimed' 2: 'two-four' 3: 'two-four' 4: 'two-four' 5: 'five-six' 6: 'five-six' 7: 'seven-eight' 8: 'seven-eight' 9: 'nine' 10: 'unclaimed' 11: 'unclaimed'
Translating in the other direction is also of interest, for example when processing values that are provided by humans in terms of the Values strings, or when using the pywbem mock support and the test cases specify property values for CIM instances in terms of the more human-readable Values strings.
Again, assuming the class shown above exists in a WBEM server, the following code will get the class from the server, create a value mapping for this property, and look up the binary property values from the Values strings:
namespace = 'root/cimv2' conn = pywbem.WBEMConnection(...) # WBEM server myprop_vm = pywbem.ValueMapping.for_property( conn, namespace, 'CIM_Foo', 'MyProp') values_strs = ["zero", "two-four", "five-six", "seven-eight", "nine", "unclaimed"] print("Values string: Binary value") for values_str in values_strs: bin_value = myprop_vm.tobinary(values_str) print("{0:12}: {1!r}".format(values_str, bin_value))
Resulting output:
Values string: Binary value 'zero': 0 'two-four': (2, 4) 'five-six': (5, 6) 'seven-eight': (7, 8) 'nine': 9 'unclaimed': None
Iterating through the pairs of ValueMap and Values entries is also possible. Assuming the class shown above exists in a WBEM server, the following code will get the class from the server, and iterate through the value mapping:
namespace = 'root/cimv2' conn = pywbem.WBEMConnection(...) # WBEM server myprop_vm = pywbem.ValueMapping.for_property( conn, namespace, 'CIM_Foo', 'MyProp') print("Values string: Binary value") for bin_value, values_str in myprop_vm.items(): print("{0:12}: {1!r}".format(values_str, bin_value))
Resulting output:
Values string: Binary value 'zero': 0 'two-four': (2, 4) 'five-six': (5, 6) 'seven-eight': (7, 8) 'nine': 9 'unclaimed': None
Methods
for_method
Factory method that returns a new ValueMapping
instance that maps CIM method return values to the Values qualifier of that method.for_parameter
Factory method that returns a new ValueMapping
instance that maps CIM parameter values to the Values qualifier defined on that parameter.for_property
Factory method that returns a new ValueMapping
instance that maps CIM property values to the Values qualifier defined on that property.items
Generator that iterates through the items of the value mapping. tobinary
Return the integer value or values for a Values string, based upon this value mapping. tovalues
Return the Values string for an element value, based upon this value mapping. Attributes
classname
Name of the CIM class defining the mapped CIM element. conn
Connection to the WBEM server containing the CIM namespace (that contains the mapped CIM element). element
The mapped CIM element. methodname
Name of the CIM method, that either is mapped itself, or that has the parameter that is mapped. namespace
Name of the CIM namespace containing the class that defines the mapped CIM element. parametername
Name of the CIM parameter that is mapped. propname
Name of the CIM property that is mapped. Details
-
classmethod
for_property
(server, namespace, classname, propname)[source]¶ Factory method that returns a new
ValueMapping
instance that maps CIM property values to the Values qualifier defined on that property.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMConnection
orWBEMServer
) – The connection to the WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class. If None, the default namespace of the connection will be used.
- classname (string) – Name of the CIM class exposing the property. The property can be defined in that class or inherited into that class.
- propname (string) – Name of the CIM property that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. KeyError
– The CIM property does not exist in the CIM class.TypeError
– The CIM property is not integer-typed.ValueError
– No Values qualifier defined on the CIM property.ValueError
– Invalid integer representation in ValueMap qualifier defined on the CIM property.
- server (
-
classmethod
for_method
(server, namespace, classname, methodname)[source]¶ Factory method that returns a new
ValueMapping
instance that maps CIM method return values to the Values qualifier of that method.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMConnection
orWBEMServer
) – The connection to the WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
- methodname (string) – Name of the CIM method that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. KeyError
– The CIM method does not exist in the CIM class.TypeError
– The CIM method is not integer-typed.ValueError
– No Values qualifier defined on the CIM method.ValueError
– Invalid integer representation in ValueMap qualifier defined on the CIM method.
- server (
-
classmethod
for_parameter
(server, namespace, classname, methodname, parametername)[source]¶ Factory method that returns a new
ValueMapping
instance that maps CIM parameter values to the Values qualifier defined on that parameter.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMConnection
orWBEMServer
) – The connection to the WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
- methodname (string) – Name of the CIM method that has the parameter.
- parametername (string) – Name of the CIM parameter that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. KeyError
– The CIM method does not exist in the CIM class.KeyError
– The CIM parameter does not exist in the CIM method.TypeError
– The CIM parameter is not integer-typed.ValueError
– No Values qualifier defined on the CIM parameter.ValueError
– Invalid integer representation in ValueMap qualifier defined on the CIM parameter.
- server (
-
__repr__
()[source]¶ Return a representation of the
ValueMapping
object with all attributes, that is suitable for debugging.
-
conn
¶ Connection to the WBEM server containing the CIM namespace (that contains the mapped CIM element).
Type: WBEMConnection
-
namespace
¶ Name of the CIM namespace containing the class that defines the mapped CIM element.
Type: string
-
methodname
¶ Name of the CIM method, that either is mapped itself, or that has the parameter that is mapped. None, if no method or parameter is mapped.
Type: string
-
parametername
¶ Name of the CIM parameter that is mapped. None, if no parameter is mapped.
Type: string
-
element
¶ The mapped CIM element.
Type: CIMProperty
,CIMMethod
, orCIMParameter
-
tovalues
(element_value)[source]¶ Return the Values string for an element value, based upon this value mapping.
Parameters: element_value (integer or
CIMInt
) – The value of the CIM element (property, method, parameter).Returns: The Values string for the element value.
Return type: Raises: ValueError
– Element value outside of the set defined by ValueMap.TypeError
– Element value is not an integer type.
-
tobinary
(values_str)[source]¶ Return the integer value or values for a Values string, based upon this value mapping.
Any returned integer value is represented as the CIM type of the element (e.g.
Uint16
).If the Values string corresponds to a single value, that single value is returned as an integer.
If the Values string corresponds to a value range (e.g. “1..” or “..2” or “3..4”), that value range is returned as a tuple with two items that are the lowest and the highest value of the range. That is the case also when the value range is open on the left side or right side.
If the Values string corresponds to the unclaimed indicator “..”, None is returned.
Parameters: values_str (string) – The Values string for the element value.
Returns: The element value or value range corresponding to the Values string, or None for unclaimed.
Return type: Raises: ValueError
– Values string outside of the set defined by Values.TypeError
– Values string is not a string type.
-
items
()[source]¶ Generator that iterates through the items of the value mapping. The items are the array entries of the Values and ValueMap qualifiers, and they are iterated in the order specified in the arrays. If the ValueMap qualifier is not specified, the default of consecutive integers starting at 0 is used as a default, consistent with DSP0004.
Each iterated item is a tuple of integer value(s) representing the ValueMap array entry, and the corresponding Values string. Any integer value in the iterated items is represented as the CIM type of the element (e.g.
Uint16
).If the Values string corresponds to a single element value, the first tuple item is that single integer value.
If the Values string corresponds to a value range (e.g. “1..” or “..2” or “3..4”), that value range is returned as a tuple with two items that are the lowest and the highest value of the range. That is the case also when the value range is open on the left side or right side.
If the Values string corresponds to the unclaimed indicator “..”, the first tuple item is None.
Returns: iterator for tuple of integer value(s) and Values string.
-
classmethod
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
andWWW-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:
- This option does not allow a server to establish the identity of the user. Its use should be limited to environments where network access is secured.
- The use of HTTP Basic Authentication is strongly discouraged, because the password is sent unencrypted over the network.
- A CA certificate is needed, unless server certificate verification is disabled via the no_verification parameter (not recommended), or unless an anonymous cipher is used for the server certificate (not recommended).
- This is the most desirable option from a security perspective, if the WBEM server is able to establish the user identity based on the client certificate.
The protocol and authentication types that can be used on a connection to a
WBEM server are set by the user when creating the
WBEMConnection
object:
- The scheme of the URL in the url parameter controls whether the HTTP or HTTPS protocol is used.
- The cred parameter may specify credentials (userid/password). If specified,
pywbem uses them for Basic Authentication at the HTTP level. Pywbem provides
an
Authenticate
HTTP header on each request, and also handles server challenges transparently to the user of the WBEM client 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 (see
DEFAULT_CA_CERT_PATHS
).
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 to be used when the ca_certs parameter of
WBEMConnection
is None. The first existing directory is used as a default for that parameter. Note that these default directory paths only work on some Linux distributions.
WBEM server API¶
New in pywbem 0.9 as experimental and finalized in 0.10.
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.
Example¶
The following example code displays some information about a WBEM server:
from pywbem import WBEMConnection, WBEMServer, ValueMapping
def explore_server(server_url, username, password):
print("WBEM server URL:\n {0}".format(server_url))
conn = WBEMConnection(server_url, (username, password))
server = WBEMServer(conn)
print("Brand:\n {0}".format(server.brand))
print("Version:\n {0}".format(server.version))
print("Interop namespace:\n {0}".format(server.interop_ns))
print("All namespaces:")
for ns in server.namespaces:
print(" {0}".format(ns))
print("Advertised management profiles:")
org_vm = ValueMapping.for_property(server, server.interop_ns,
'CIM_RegisteredProfile', 'RegisteredOrganization')
for inst in server.profiles:
org = org_vm.tovalues(inst['RegisteredOrganization'])
name = inst['RegisteredName']
vers = inst['RegisteredVersion']
print(" {0} {1} Profile {2}".format(org, name, vers))
Example output:
WBEM server URL:
http://0.0.0.0
Brand:
OpenPegasus
Version:
2.12.0
Interop namespace:
root/PG_Interop
All namespaces:
root/PG_InterOp
root/PG_Internal
root/cimv2
root
Advertised management profiles:
SNIA Indication Profile 1.1.0
SNIA Indication Profile 1.2.0
SNIA Software Profile 1.1.0
SNIA Software Profile 1.2.0
SNIA Profile Registration Profile 1.0.0
SNIA SMI-S Profile 1.2.0
SNIA Server Profile 1.1.0
SNIA Server Profile 1.2.0
DMTF Profile Registration Profile 1.0.0
DMTF Indications Profile 1.1.0
WBEMServer¶
-
class
pywbem.
WBEMServer
(conn)[source]¶ New in pywbem 0.9 as experimental and finalized in 0.10.
A representation of a WBEM server that serves as a general access point to a client.
It supports determining the Interop namespace of the server, all namespaces, its brand and version, the advertised management profiles and finally allows retrieving the central instances of an implementation of a management profile with one method invocation regardless of whether the profile implementation chose to implement the central or scoping class profile advertisement methodology (see section Profile advertisement methodologies).
It also provides functions to subscribe for indications.
Parameters: conn ( WBEMConnection
) – Connection to the WBEM server.Methods
create_namespace
Create the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the new namespace there. delete_namespace
Delete the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the removed namespace there. get_central_instances
Return the instance paths of the central instances of a management profile. get_selected_profiles
Return the CIM_RegisteredProfile instances representing a filtered subset of the management profiles advertised by the WBEM server, that can be filtered by registered organization, registered name, and/or registered version. Attributes
INTEROP_NAMESPACES
A class variable with the possible names of Interop namespaces that should be tried when determining the Interop namespace on the WBEM server. NAMESPACE_CLASSNAMES
A class variable with the possible names of CIM classes for representing CIM namespaces, that should be tried when determining the namespaces on the WBEM server. brand
Brand of the WBEM server. cimom_inst
CIM instance of class CIM_ObjectManager that represents the WBEM server. conn
Connection to the WBEM server. interop_ns
Name of the Interop namespace of the WBEM server. namespace_classname
Name of the CIM class that was found to represent the CIM namespaces of the WBEM server. namespace_paths
Instance paths of the CIM instances in the Interop namespace that represent the namespaces of the WBEM server. namespaces
Names of all namespaces of the WBEM server. profiles
The CIM_RegisteredProfile instances representing all management profiles advertised by the WBEM server. url
URL of the WBEM server. version
Version of the WBEM server. Details
-
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.
-
__str__
()[source]¶ Return a representation of the
WBEMServer
object with a subset of its attributes.
-
__repr__
()[source]¶ Return a representation of the
WBEMServer
object with all attributes, that is suitable for debugging.
-
conn
¶ Connection to the WBEM server.
Type: WBEMConnection
-
interop_ns
¶ Name of the Interop namespace of the WBEM server.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
Type: - Exceptions raised by
-
namespace_classname
¶ Name of the CIM class that was found to represent the CIM namespaces of the WBEM server.
Raises: - Exceptions raised by
WBEMConnection
. ModelError
– An issue with the model implemented by the WBEM server.CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
Type: - Exceptions raised by
-
namespaces
¶ Names of all namespaces of the WBEM server.
Raises: - Exceptions raised by
WBEMConnection
. ModelError
– An issue with the model implemented by the WBEM server.CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
Type: list
of string- Exceptions raised by
-
namespace_paths
¶ Instance paths of the CIM instances in the Interop namespace that represent the namespaces of the WBEM server.
Note: One WBEM server has been found to support an Interop namespace without representing it as a CIM instance. In that case, this property will not have an instance path for the Interop namespace, but the
namespaces
property will have the name of the Interop namespace.Raises: - Exceptions raised by
WBEMConnection
. ModelError
– An issue with the model implemented by the WBEM server.CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
Type: list
ofCIMInstanceName
- Exceptions raised by
-
brand
¶ Brand of the WBEM server.
The brand is determined from the CIM_ObjectManager instance in the Interop namespace, by looking at its ElementName property.
For known WBEM servers, the brand is then normalized in order to make it identifiable:
"OpenPegasus"
"SFCB"
(Small Footprint CIM Broker)"WBEM Solutions J WBEM Server"
"EMC CIM Server"
"FUJITSU CIM Object Manager"
For all other WBEM servers, the brand is the value of the ElementName property, or the string
"unknown"
, if that property is not set or the empty string.Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
Type:
-
version
¶ Version of the WBEM server.
None, if the version cannot be determined.
The version is determined from the CIM_ObjectManager instance in the Interop namespace, by looking at its ElementName property, or if that is not set, at its Description property, and by taking the string after
"version"
or"release"
(case insensitively).Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
Type: - Exceptions raised by
-
cimom_inst
¶ CIM instance of class CIM_ObjectManager that represents the WBEM server.
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.
Type: - Exceptions raised by
-
profiles
¶ The CIM_RegisteredProfile instances representing all management profiles advertised by the WBEM server.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
Type: list
ofCIMInstance
- Exceptions raised by
-
create_namespace
(namespace)[source]¶ Create the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the new namespace there.
This method attempts the following approaches for creating the namespace, in order, until an approach succeeds:
Namespace creation as described in the WBEM Server profile (DSP1092) via CIM method CIM_WBEMServer.CreateWBEMServerNamespace().
This is a new standard approach that is not likely to be widely implemented yet.
Issuing the CreateInstance operation using the CIM class representing namespaces (‘PG_Namespace’ for OpenPegasus, and ‘CIM_Namespace’ otherwise), against the Interop namespace.
This approach is typically supported in WBEM servers that support the creation of CIM namespaces. This approach is similar to the approach described in DSP0200.
Creating namespaces using the __Namespace pseudo-class has been deprecated already in DSP0200 1.1.0 (released in 01/2003), and pywbem does not implement that approach.
Parameters: namespace (string) – CIM namespace name. Must not be None. The namespace may contain leading and a trailing slash, both of which will be ignored.
Returns: The specified CIM namespace name in its standard format (i.e. without leading or trailing slash characters).
Return type: Raises: - Exceptions raised by
WBEMConnection
. ModelError
– An issue with the model implemented by the WBEM server.CIMError
– CIM_ERR_ALREADY_EXISTS, Specified namespace already exists in the WBEM server.CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.CIMError
– CIM_ERR_FAILED, Unexpected number of central instances of WBEM Server profile.
-
delete_namespace
(namespace)[source]¶ Delete the specified CIM namespace in the WBEM server and update this WBEMServer object to reflect the removed namespace there.
The specified namespace must be empty (i.e. must not contain any classes, instances, or qualifier types.
This method attempts the following approaches for deleting the namespace, in order, until an approach succeeds:
Issuing the DeleteInstance operation using the CIM class representing namespaces (‘PG_Namespace’ for OpenPegasus, and ‘CIM_Namespace’ otherwise), against the Interop namespace.
This approach is typically supported in WBEM servers that support the creation of CIM namespaces. This approach is similar to the approach described in DSP0200.
The approach described in the WBEM Server profile (DSP1092) via deleting the CIM_WBEMServerNamespace instance is not implemented because that would also delete any classes, instances, and qualifier types in the namespace.
Deleting namespaces using the __Namespace pseudo-class has been deprecated already in DSP0200 1.1.0 (released in 01/2003), and pywbem does not implement that approach.
Parameters: namespace (string) – CIM namespace name. Must not be None. The namespace may contain leading and a trailing slash, both of which will be ignored.
Returns: The specified CIM namespace name in its standard format (i.e. without leading or trailing slash characters).
Return type: Raises: - Exceptions raised by
WBEMConnection
. ModelError
– An issue with the model implemented by the WBEM server.CIMError
– CIM_ERR_NOT_FOUND, Specified namespace does not exist.CIMError
– CIM_ERR_NAMESPACE_NOT_EMPTY, Specified namespace is not empty.- Additional CIM errors.
-
get_selected_profiles
(registered_org=None, registered_name=None, registered_version=None)[source]¶ Return the CIM_RegisteredProfile instances representing a filtered subset of the management profiles advertised by the WBEM server, that can be filtered by registered organization, registered name, and/or registered version.
Parameters: - registered_org (string) – A filter for the registered organization of the profile, matching (case insensitively) the RegisteredOrganization property of the CIM_RegisteredProfile instance, via its Values qualifier. If None, this parameter is ignored for filtering.
- registered_name (string) – A filter for the registered name of the profile, matching (case insensitively) the RegisteredName property of the CIM_RegisteredProfile instance. If None, this parameter is ignored for filtering.
- registered_version (string) – A filter for the registered version of the profile, matching (case insensitively) the RegisteredVersion property of the CIM_RegisteredProfile instance. Note that version strings may contain aplhabetic characters to indicate the draft level. If None, this parameter is ignored for filtering.
Returns: The CIM_RegisteredProfile instances representing the filtered subset of the management profiles advertised by the WBEM server.
Return type: list
ofCIMInstance
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, reference_direction='dmtf', try_gci_method=False)[source]¶ Return the instance paths of the central instances of a management profile.
DMTF defines the following profile advertisement methodologies in DSP1033:
- GetCentralInstances methodology (new in DSP1033 1.1, only when explicitly requested by the caller)
- Central class methodology
- Scoping class methodology
A brief explanation of these methodologies can be found in section Profile advertisement methodologies.
Pywbem attempts all three profile advertisement methodologies in the order listed above.
All three methodologies start from the CIM_RegisteredProfile instance referenced by the profile_path parameter. That instance represents a management profile. In case of multiple uses of a component profile in a WBEM server, one such instance is supposed to represent one such profile use.
If the profile is a component profile and its implementation does not support the GetCentralInstances or central class methodologies, the central_class, scoping_class, and scoping_path parameters are required in order for the method to attempt the scoping class methodology. The method will not fail if these parameters are not provided, as long as the profile implementation supports the GetCentralInstances or central class methodology.
Example parameters for a 1-hop scoping path:
central_class = "CIM_Fan"
scoping_path = ["CIM_SystemDevice"]
scoping_class = "CIM_ComputerSystem"
Example parameters for a 2-hop scoping path:
central_class = "CIM_Sensor"
scoping_path = ["CIM_AssociatedSensor", "CIM_Fan", "CIM_SystemDevice"]
scoping_class = "CIM_ComputerSystem"
Parameters: - profile_path (
CIMInstanceName
) – Instance path of the CIM_RegisteredProfile instance representing the management profile (or its use, if there are multiple uses in a WBEM server). - central_class (string) –
Class name of central class defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- scoping_class (string) –
Class name of scoping class defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- scoping_path (list of string) –
Scoping path defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- reference_direction (string) –
Defines the navigation direction across the CIM_ReferencedProfile association when navigating from the current profile to its scoping (= referencing, autonomous) profile when using the scoping class methodology, as follows:
- ’dmtf’ (default): Assume DMTF conformance, i.e. the ‘Dependent’ end is followed.
- ’snia’: Assume SNIA SMI-S conformance, i.e. the ‘Antecedent’ end is followed.
This parameter supports the different definitions between DMTF and SNIA SMI-S standards regarding the use of the two ends of the CIM_ReferencedProfile association:
- The DMTF standards define in DSP1033 and DSP1001:
- Antecedent = referenced profile = component profile
- Dependent = referencing profile = autonomous profile
- The SNIA SMI-S standard defines in the “Profile Registration
Profile” (in the SMI-S “Common Profiles” book):
- Antecedent = autonomous profile
- Dependent = component (= sub) profile
It should be assumed that all profiles that are directly or indirectly scoped by a particular top-level (= wrapper) specification implement the reference direction that matches the registered organisation of the top-level specification.
Examples:
- All profiles scoped by the SNIA SMI-S top-level specification should be assumed to implement the ‘snia’ reference direction.
- All profiles scoped by the DMTF SMASH wrapper specification should be assumed to implement the ‘dmtf’ reference direction.
- try_gci_method (
bool
) – Flag indicating that the GetCentralInstances methodology should be attempted. This methodology is not expected to be implemented by WBEM servers at this point, and causes undesirable behavior with some WBEM servers, so it is not attempted by default. Note that WBEM servers are required to support the scoping class methodology.
Returns: The instance paths of the central instances of the implementation of the management profile.
Return type: list
ofCIMInstanceName
Raises: - Exceptions raised by
WBEMConnection
. ModelError
– Model implementation errors on the server.ValueError
– User errors regarding input parameter values.TypeError
– User errors regarding input parameter types.
-
WBEM indication API¶
New in pywbem 0.9 as experimental and finalized in 0.10.
The WBEM indication API supports subscription for and receiving of CIM indications.
This chapter has the following sections:
- WBEMListener - The
WBEMListener
class provides a thread-based WBEM listener service for receiving indications. - WBEMSubscriptionManager - The
WBEMSubscriptionManager
class provides for managing subscriptions for indications.
WBEMListener¶
New in pywbem 0.9 as experimental and finalized in 0.10.
The WBEMListener
class provides a thread-based WBEM listener
service that can receive CIM indications from multiple WBEM servers and that
calls registered callback functions to deliver the received indications.
Examples¶
The following example creates and runs a listener:
import 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():
# Configure logging of the listener via the Python root logger
logging.basicConfig(filename='listener.log', level=logging.WARNING,
format='%(asctime)s - %(levelname)s - %(message)s)
certkeyfile = 'listener.pem'
listener = WBEMListener(host=getfqdn()
http_port=5988,
https_port=5989,
certfile=certkeyfile,
keyfile=certkeyfile)
listener.add_callback(process_indication)
try:
listener.start()
# process_indication() will be called for each received indication
... # wait for some condition to end listening
finally:
listener.stop()
Alternative code using the class as a context manager:
with WBEMListener(...) as listener:
listener.add_callback(process_indication)
listener.start()
# process_indication() will be called for each received indication
... # wait for some condition to end listening
# listener.stop() has been called automatically
See the example in section WBEMSubscriptionManager for an example of using a listener in combination with a subscription manager.
Another listener example is in the script examples/listen.py
(when you
clone the GitHub pywbem/pywbem project). It is an interactive Python shell that
creates a listener and displays any indications it receives, in MOF format.
Logging in the listener¶
Each WBEMListener
object has its own separate Python logger
object with the name:
‘pywbem.listener.{id}’
where {id} is a string that is unique for each WBEMListener
object within the Python process.
The logger
property of a
WBEMListener
object provides access to that Python logger
object, if needed.
The listener will log any indications it receives and any responses it sends
back to the indication sender, at the logging.INFO
logging level.
In addition, it will log errors at the logging.ERROR
logging level.
Since Python 2.7, the Python root logger will by default (i.e. when not being
configured) print log records of logging level logging.WARNING
or
greater to sys.stderr. So the indication and response interactions will not
be printed by default, but any errors logged at the logging.ERROR
logging level will be printed by default.
Pywbem adds a null handler to the logger named ‘pywbem’, in order to prevent the “No handlers could be found for logger …” warning. This follows best practices recommended in Configuring logging for a library and in several articles, for example in this article. Because this warning is no longer issued on Python 3.4 and higher, pywbem adds a null handler only on Python 2.6 and 2.7.
WBEMListener class¶
-
class
pywbem.
WBEMListener
(host, http_port=None, https_port=None, certfile=None, keyfile=None)[source]¶ New in pywbem 0.9 as experimental and finalized in 0.10.
A WBEM listener.
The listener supports starting and stopping threads that listen for CIM-XML ExportIndication messages using HTTP and/or HTTPS, and that pass any received indications on to registered callback functions.
The listener must be stopped in order to free the TCP/IP port it listens on. Using this class as a context manager ensures that the listener is stopped when leaving the context manager scope.
Parameters: - host (string) – IP address or host name at which this listener can be reached.
- http_port (string or integer) –
HTTP port at which this listener can be reached. Note that at least one port (HTTP or HTTPS) must be set.
None means not to set up a port for HTTP.
- https_port (string or integer) –
HTTPS port at which this listener can be reached.
None means not to set up a port for HTTPS.
- certfile (string) –
File path of certificate file to be used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
It is valid for the certificate file to contain a private key; the server certificate sent during SSL/TLS handshake is sent without the private key.
None means not to use a server certificate file. Setting up a port for HTTPS requires specifying a certificate file.
- keyfile (string) –
File path of private key file to be used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
It is valid to specify a certificate file that contains a private key.
None means not to use a private key file. Setting up a port for HTTPS requires specifying a private key file.
Methods
add_callback
Add a callback function to the listener. deliver_indication
This function is called by the listener threads for each received indication. start
Start the WBEM listener threads, if they are not yet running. stop
Stop the WBEM listener threads, if they are running. Attributes
certfile
File path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection. host
IP address or host name at which this listener can be reached. http_port
HTTP port at which this listener can be reached. http_started
Boolean indicating whether the listener is started for the HTTP port. https_port
HTTPS port at which this listener can be reached. https_started
Boolean indicating whether the listener is started for the HTTPS port. keyfile
File path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection. logger
Logger object for this listener. Details
-
__str__
()[source]¶ Return a representation of the
WBEMListener
object with a subset of its attributes.
-
__repr__
()[source]¶ Return a representation of the
WBEMListener
object with all attributes, that is suitable for debugging.
-
__enter__
()[source]¶ New in pywbem 0.12.
Enter method when the class is used as a context manager.
Returns the listener object.
-
__exit__
(exc_type, exc_value, traceback)[source]¶ New in pywbem 0.12.
Exit method when the class is used as a context manager.
Stops the listener by calling
stop()
.
-
http_port
¶ HTTP port at which this listener can be reached.
None means there is no port set up for HTTP.
Type: integer
-
https_port
¶ HTTPS port at which this listener can be reached.
None means there is no port set up for HTTPS.
Type: integer
-
http_started
¶ Boolean indicating whether the listener is started for the HTTP port.
If no port is set up for HTTP, False is returned.
New in pywbem 0.12.
Type: bool
-
https_started
¶ Boolean indicating whether the listener is started for the HTTPS port.
If no port is set up for HTTPS, False is returned.
New in pywbem 0.12.
Type: bool
-
certfile
¶ File path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
None means there is no certificate file being used (that is, no port is set up for HTTPS).
Type: string
-
keyfile
¶ File path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
None means there is no certificate file being used (that is, no port is set up for HTTPS).
Type: string
-
logger
¶ Logger object for this listener.
Each listener object has its own separate logger object with the name:
‘pywbem.listener.{id}’where {id} is a unique string for each listener object.
Users of the listener should not look up the logger object by name, but should use this property to get to it.
Type: logging.Logger
-
start
()[source]¶ Start the WBEM listener threads, if they are not yet running.
A thread serving CIM-XML over HTTP is started if an HTTP port was specified for the listener. A thread serving CIM-XML over HTTPS is started if an HTTPS port was specified for the listener.
These server threads will handle the ExportIndication export message described in DSP0200 and they will invoke the registered callback functions for any received CIM indications.
The listener must be stopped again in order to free the TCP/IP port it listens on. The listener can be stopped explicitly using the
stop()
method. The listener will be automatically stopped when the main thread terminates (i.e. when the Python process terminates), or whenWBEMListener
is used as a context manager when leaving its scope.Raises: OSError
– witherrno
=errno.EADDRINUSE
when the WBEM listener port is already in use.
-
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.
- 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]¶ New in pywbem 0.9 as experimental and finalized in 0.10.
Interface of a callback function that is provided by the user of the API and that will be called by the listener for each received CIM indication.
Parameters: - indication (
CIMInstance
) – Representation of the CIM indication that has been received. Its path attribute is None. - host (string) – Host name or IP address of WBEM server sending the indication.
Raises: Exception
– If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.- indication (
WBEMSubscriptionManager¶
New in pywbem 0.9 as experimental and finalized in 0.10.
The WBEMSubscriptionManager
class is a subscription manager
that provides for creating and removing indication subscriptions (including
indication filters and listener destinations) for multiple WBEM servers and
multiple WBEM listeners and for getting information about existing indication
subscriptions.
The WBEM listener is identified through its URL, so it may be the pywbem
listener (that is, a WBEMListener
object) or any other WBEM
listener.
This subscription manager supports three types of ownership of the CIM instances in WBEM servers that represent subscriptions, filters and listener destinations:
Owned
Owned CIM instances are created via the subscription manager and their life cycle is bound to the life cycle of the registration of that WBEM server with the subscription manager via
add_server()
.Owned CIM instances are deleted automatically when their WBEM server is deregistered from the subscription manager via
remove_server()
orremove_all_servers()
. In addition, they can be deleted by the user via the removal methods of theWBEMSubscriptionManager
class.Permanent
Permanent CIM instances are created via the subscription manager and their life cycle is independent of the life cycle of the registration of that WBEM server with the subscription manager.
Permanent CIM instances are not deleted automatically when their WBEM server is deregistered from the subscription manager. The user is responsible for their lifetime management: They can be deleted via the removal methods of the
WBEMSubscriptionManager
class.Static
Static CIM instances pre-exist in the WBEM server and cannot be deleted (or created) by a WBEM client.
If a client creates a subscription between a filter and a listener destination, the types of ownership of these three CIM instances may be arbitrarily mixed, with one exception:
- A permanent subscription cannot be created on an owned filter or an owned
listener destination. Allowing that would prevent the automatic life cycle
management of the owned filter or listener destination by the subscription
manager. This restriction is enforced by the
WBEMSubscriptionManager
class.
The WBEMSubscriptionManager
object remembers owned
subscriptions, filters, and listener destinations. If for some reason that
object gets deleted before all servers could be removed (e.g. because the
Python program aborts), 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]¶ New in pywbem 0.9 as experimental and finalized in 0.10.
A class for managing subscriptions for CIM indications in a WBEM server.
The class may be used as a Python context manager, in order to get automatic clean up (see
__exit__()
).Parameters: subscription_manager_id (string) –
A subscription manager ID string that is used as a component in the value of the Name property of indication filter and listener destination instances 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
– Incorrect input parameter values.TypeError
– Incorrect input parameter types.
Methods
add_filter
Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class “CIM_IndicationFilter”) in the Interop namespace of the server. add_listener_destinations
Register WBEM listeners to be the target of indications sent by a WBEM server. add_server
Register a WBEM server with the subscription manager. add_subscriptions
Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destinations, by creating indication subscription instances (of CIM class “CIM_IndicationSubscription”) in the Interop namespace of that server. get_all_destinations
Return all listener destinations in a WBEM server. get_all_filters
Return all indication filters in a WBEM server. get_all_subscriptions
Return all indication subscriptions in a WBEM server. get_owned_destinations
Return the listener destinations in a WBEM server owned by this subscription manager. get_owned_filters
Return the indication filters in a WBEM server owned by this subscription manager. get_owned_subscriptions
Return the indication subscriptions in a WBEM server owned by this subscription manager. remove_all_servers
Remove all registered WBEM servers from the subscription manager. remove_destinations
Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server. remove_filter
Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server. remove_server
Remove a registered WBEM server from the subscription manager. remove_subscriptions
Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server. Attributes
Details
-
__str__
()[source]¶ Return a representation of the
WBEMSubscriptionManager
object with a subset of its attributes.
-
__repr__
()[source]¶ Return a representation of the
WBEMSubscriptionManager
object with all attributes, that is suitable for debugging.
-
__enter__
()[source]¶ New in pywbem 0.10.
Enter method when the class is used as a context manager. Returns the subscription manager object
-
__exit__
(exc_type, exc_value, traceback)[source]¶ New in pywbem 0.10.
Exit method when the class is used as a context manager.
It cleans up by calling
remove_all_servers()
.
-
add_server
(server)[source]¶ Register a WBEM server with the subscription manager. This is a prerequisite for adding listener destinations, indication filters and indication subscriptions to the server.
This method discovers listener destination, indication filter, and subscription instances in the WBEM server owned by this subscription manager, and registers them in the subscription manager as if they had been created through it.
In this discovery process, listener destination and indication filter instances are matched based upon the value of their Name property. Subscription instances are matched based upon the ownership of the referenced destination and filter instances: If a subscription references a filter or a destination that is owned by this subscription manager, it is considered owned by this subscription manager as well.
Parameters: server (
WBEMServer
) – The WBEM server.Returns: An ID for the WBEM server, for use by other methods of this class.
Return type: Raises: - Exceptions raised by
WBEMConnection
. ValueError
– Incorrect input parameter values.TypeError
– Incorrect input parameter types.
- Exceptions raised by
-
remove_server
(server_id)[source]¶ Remove a registered WBEM server from the subscription manager. This also unregisters listeners from that server and removes all owned indication subscriptions, owned indication filters and owned listener destinations.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Raises: Exceptions raised by WBEMConnection
.
-
remove_all_servers
()[source]¶ Remove all registered WBEM servers from the subscription manager. This also unregisters listeners from these servers and removes all owned indication subscriptions, owned indication filters, and owned listener destinations.
Raises: Exceptions raised by WBEMConnection
.
-
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. If 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
ofCIMInstance
Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-
get_owned_destinations
(server_id)[source]¶ Return the listener destinations in a WBEM server owned by this subscription manager.
This function accesses only the local list of owned destinations; it does not contact the WBEM server. The local list of owned destinations is discovered from the WBEM server when the server is registered with the subscription manager, and is maintained from then on as changes happen through this subscription manager.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The listener destination instances. Return type: list
ofCIMInstance
-
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
ofCIMInstance
Raises: Exceptions raised by WBEMConnection
.
-
remove_destinations
(server_id, destination_paths)[source]¶ Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.
The listener destinations must be owned or permanent (i.e. not static).
This method verifies that there are not currently any subscriptions on the listener destinations to be removed, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - destination_paths (
CIMInstanceName
or list ofCIMInstanceName
) – Instance path(s) of the listener destination instance(s) in the WBEM server.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_FAILED, if there are referencing subscriptions.
- server_id (string) – The server ID of the WBEM server, returned by
-
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. If 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) –
New in pywbem 0.10.
The filter name to be used directly for the Name property of the filter instance, or None if the filter_id parameter is specified.
Returns: The created indication filter instance.
Return type: Raises: - Exceptions raised by
WBEMConnection
. ValueError
– Incorrect input parameter values.TypeError
– Incorrect input parameter types.
-
get_owned_filters
(server_id)[source]¶ Return the indication filters in a WBEM server owned by this subscription manager.
This function accesses only the local list of owned filters; it does not contact the WBEM server. The local list of owned filters is discovered from the WBEM server when the server is registered with the the subscription manager, and is maintained from then on as changes happen through this subscription manager.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The indication filter instances. Return type: list
ofCIMInstance
-
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
ofCIMInstance
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.
- server_id (string) – The server ID of the WBEM server, returned by
-
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. If 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 ofCIMInstanceName
) –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
ofCIMInstance
Raises: - Exceptions raised by
WBEMConnection
. ValueError
– Incorrect input parameter values.
- server_id (string) – The server ID of the WBEM server, returned by
-
get_owned_subscriptions
(server_id)[source]¶ Return the indication subscriptions in a WBEM server owned by this subscription manager.
This function accesses only the local list of owned subscriptions; it does not contact the WBEM server. The local list of owned subscriptions is discovered from the WBEM server when the server is registered with the subscription manager, and is maintained from then on as changes happen through this subscription manager.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The indication subscription instances. Return type: list
ofCIMInstance
-
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
ofCIMInstance
Raises: Exceptions raised by WBEMConnection
.
-
remove_subscriptions
(server_id, sub_paths)[source]¶ Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.
The indication subscriptions must be owned or permanent (i.e. not static).
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - sub_paths (
CIMInstanceName
or list ofCIMInstanceName
) – Instance path(s) of the indication subscription instance(s) in the WBEM server.
Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
MOF compiler API¶
The language in which CIM classes, CIM Instances, etc. are specified, is called MOF (for Managed Object Format). It is defined in DSP0004.
MOF compilers take MOF files as input, compile them and use the result (CIM classes, instances, and/or qualifier declarations) to update a target CIM repository. The repository may initially be empty, or may contain CIM classes, instances, and/or qualifier declarations that are used to resolve dependencies the new MOF compilation may have.
The pywbem package includes a MOF compiler that is provided in two forms:
- as an API (described in this chapter)
- as a command (described in section mof_compiler)
The pywbem MOF compiler will compile MOF files whose syntax complies with DSP0004, with some limitations:
- Although there is no formal keyword list of illegal words for property/parameter.etc. names , there is a list of mof syntax tokens in DSP0004 section A.3. Generally these should not be used as property names. The pywbem MOF compiler largely enforces this so that words like ‘indication’ are not allowed as property/parameter/etc. names.
- The key properties of instances with aliases must be initialized in the instance specification, or their default values must be non-NULL. (See pywbem issue #1079).
- An alias must be defined before it is used. In DSP0004, no such requirement is documented. (See pywbem issue #1079).
The MOF compiler API provides for invoking the MOF compiler, it supports
plugging in a user-provided CIM repository (see
BaseRepositoryConnection
), and it supports a rollback
capability that undoes compilation effects (see
rollback()
).
The MOF compiler API consists of the following parts, which are described in the remaining sections of this chapter:
- MOFCompiler Class - Describes the
MOFCompiler
class, which allows invoking the MOF compiler programmatically. - Repository connections - Describes the
BaseRepositoryConnection
class that defines the interface for connecting to a CIM repository, and theMOFWBEMConnection
class that is a connection to an in-memory repository on top of an underlying repository, and is used by the MOF compiler to provide rollback support. - Exceptions - Describes the exceptions that can be raised by the MOF compiler API.
MOFCompiler Class¶
-
class
pywbem.
MOFCompiler
(handle, search_paths=None, verbose=False, log_func=<function _print_logger>)[source]¶ A MOF compiler. See MOF compiler API for an explanation of MOF compilers in general.
A MOF compiler may be associated with one CIM repository. The repository is used for looking up dependent CIM elements (e.g. the superclass specified in a class whose MOF definition is being compiled), and it is also updated with the result of the compilation. A repository contains CIM namespaces, and the namespaces contain CIM classes, instances and qualifier types.
The association of a MOF compiler with a CIM repository is established when creating an object of this class. The interactions with the CIM repository are defined in the abstract base class
BaseRepositoryConnection
.Parameters: - handle (BaseRepositoryConnection or
WBEMConnection
) –A handle identifying the CIM repository that will be associated with the MOF compiler.
If the provided object is a repository connection (i.e. derived from
BaseRepositoryConnection
, typically that would be aMOFWBEMConnection
object), it is directly used by the MOF compiler to interface with the repository.If the provided object is a WBEM connection (i.e.
WBEMConnection
orFakedWBEMConnection
), aMOFWBEMConnection
object is created from the provided object, and used by the MOF compiler to interface with the repository.None means that no CIM repository will be associated. In this case, the MOF compiler can only process standalone MOF that does not depend on existing CIM elements in the repository.
- search_paths (iterable of string or string) –
Directory path name(s) where the MOF compiler will search for MOF dependent files if the MOF element they define is not in the target namespace of the CIM repository. The compiler searches the specified directories and their subdirectories.
MOF dependent files are:
- The MOF file defining the superclass of a class that is compiled. The MOF file searched for is ‘<classname>.mof’.
- The MOF file defining the qualifier type of a qualifier that is specified on a MOF element that is compiled. The MOF files searched for are ‘qualifiers.mof’ and ‘qualifiers_optional.mof’.
- The MOF file of a class specified in a reference property or in the EmbeddedInstance qualifier that is compiled. The MOF file searched for is ‘<classname>.mof’. This is only partly implemented, see issue #1138.
Note that MOF include files are not searched for; they are specified in the
pragma include
directive as a file path relative to the including file. - verbose (
bool
) – Indicates whether to issue more detailed compiler messages. - log_func (callable) – A logger function that is invoked for each compiler message. The logger function must take one parameter of string type. The default logger function prints to stdout.
Methods
compile_file
Compile a MOF file into a namespace of the associated CIM repository. compile_string
Compile a string of MOF statements into a namespace of the associated CIM repository. find_mof
Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler. rollback
Rollback any changes to the CIM repository that were performed by compilations using this MOF compiler object, since the object was created. Attributes
Details
-
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: IOError
– MOF file not found.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: Raises: IOError
– MOF file not found.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: Path name of the MOF file defining the CIM class, if it was found. None, if it was not found. Return type: string
- handle (BaseRepositoryConnection or
Repository connections¶
-
class
pywbem.
BaseRepositoryConnection
[source]¶ An abstract base class for implementing CIM repository connections (or an entire CIM repository) for use by the MOF compiler. This class defines the interface that is used by the
MOFCompiler
class when it interacts with its associated CIM repository.Class
MOFCompiler
invokes only the WBEM operations that are defined as methods on this class:EnumerateInstanceNames()
- Enumerate the paths of CIM instances in the repository.CreateInstance()
- Create a CIM instance in the repository.ModifyInstance()
- Modify a CIM instance in the repository.DeleteInstance()
- Delete a CIM instance in the repository.GetClass()
- Retrieve a CIM class from the repository.ModifyClass()
- Modify a CIM class in the repository.CreateClass()
- Create a CIM class in the repository.DeleteClass()
- Delete a CIM class in the repository.EnumerateQualifiers()
- Enumerate CIM qualifier types in the repository.GetQualifier()
- Retrieve a CIM qualifier type from the repository.SetQualifier()
- Create or modify a CIM qualifier type in the repository.DeleteQualifier()
- Delete a qualifier type from the repository.
Raises: Implementation classes should raise only exceptions derived from Error
. Other exceptions are considered programming errors.Methods
CreateClass
Create a CIM class in a namespace of the CIM repository. CreateInstance
Create a CIM instance in a namespace of the CIM repository. DeleteClass
Delete a CIM class in a namespace of the CIM repository. DeleteInstance
Delete a CIM instance in a namespace of the CIM repository. DeleteQualifier
Delete a CIM qualifier type in a namespace of the CIM repository. EnumerateInstanceNames
Enumerate the instance paths of CIM instances in a namespace of the CIM repository. EnumerateQualifiers
Enumerate the CIM qualifier types in a namespace of the CIM repository. GetClass
Retrieve a CIM class in a namespace of the CIM repository. GetQualifier
Retrieve a CIM qualifier type in a namespace of the CIM repository. ModifyClass
Modify a CIM class in a namespace of the CIM repository. ModifyInstance
Modify a CIM instance in a namespace of the CIM repository. SetQualifier
Create or modify a CIM qualifier type in a namespace of the CIM repository. Attributes
default_namespace
The default repository namespace. Details
-
EnumerateInstanceNames
(*args, **kwargs)[source]¶ Enumerate the instance paths of CIM instances in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.EnumerateInstanceNames()
.
-
CreateInstance
(*args, **kwargs)[source]¶ Create a CIM instance in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.CreateInstance()
.
-
ModifyInstance
(*args, **kwargs)[source]¶ Modify a CIM instance in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.ModifyInstance()
.
-
DeleteInstance
(*args, **kwargs)[source]¶ Delete a CIM instance in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.DeleteInstance()
.
-
GetClass
(*args, **kwargs)[source]¶ Retrieve a CIM class in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.GetClass()
.
-
ModifyClass
(*args, **kwargs)[source]¶ Modify a CIM class in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.ModifyClass()
.
-
CreateClass
(*args, **kwargs)[source]¶ Create a CIM class in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.CreateClass()
.
-
DeleteClass
(*args, **kwargs)[source]¶ Delete a CIM class in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.DeleteClass()
.
-
EnumerateQualifiers
(*args, **kwargs)[source]¶ Enumerate the CIM qualifier types in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.EnumerateQualifiers()
.
-
GetQualifier
(*args, **kwargs)[source]¶ Retrieve a CIM qualifier type in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.GetQualifier()
.
-
SetQualifier
(*args, **kwargs)[source]¶ Create or modify a CIM qualifier type in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.SetQualifier()
.
-
DeleteQualifier
(*args, **kwargs)[source]¶ Delete a CIM qualifier type in a namespace of the CIM repository.
For a description of the parameters, see
pywbem.WBEMConnection.DeleteQualifier()
.
-
class
pywbem.
MOFWBEMConnection
(conn=None)[source]¶ A CIM repository connection to an in-memory repository on top of an underlying repository, that is used by the MOF compiler to provide rollback support.
This class implements the
BaseRepositoryConnection
interface.Raises: The methods of this class may raise any exceptions described for class WBEMConnection
.Parameters: conn (BaseRepositoryConnection) – The underlying repository connection.
None means that there is no underlying repository and all operations performed through this object will fail.
Methods
CreateClass
Create a CIM class in the local repository of this class. CreateInstance
Create a CIM instance in the local repository of this class. DeleteClass
This method is only invoked by rollback()
(on the underlying repository), and never by the MOF compiler, and is therefore not implemented.DeleteInstance
This method is only invoked by rollback()
(on the underlying repository), and never by the MOF compiler, and is therefore not implemented.DeleteQualifier
This method is only invoked by rollback()
(on the underlying repository), and never by the MOF compiler, and is therefore not implemented.EnumerateInstanceNames
This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND. EnumerateQualifiers
Enumerate the qualifier types in the local repository of this class. GetClass
Retrieve a CIM class from the local repository of this class. GetQualifier
Retrieve a qualifier type from the local repository of this class. ModifyClass
This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class. ModifyInstance
This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance. SetQualifier
Create or modify a qualifier type in the local repository of this class. getns
string: Return the default repository namespace to be used. rollback
Remove classes and instances from the underlying repository, that have been created in the local repository of this class. setns
Set the default repository namespace to be used. Attributes
default_namespace
The default repository namespace to be used. Details
-
getns
()¶ string: Return the default repository namespace to be used.
This method exists for compatibility. Use the
default_namespace
property instead.
-
setns
(value)¶ Set the default repository namespace to be used.
This method exists for compatibility. Use the
default_namespace
property instead.
-
default_namespace
¶ The default repository namespace to be used.
The default repository namespace is the default namespace of the underlying repository connection if there is such an underlying connection, or the default namespace of this object.
Initially, the default namespace of this object is ‘root/cimv2’.
This property is settable. Setting it will cause the default namespace of the underlying repository connection to be updated if there is such an underlying connection, or the default namespace of this object.
Type: string
-
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.
-
Exceptions¶
The MOF compiler API may raise the exceptions that can be raised by the
WBEM client library API, and in addition the
MOFParseError
exception.
-
class
pywbem.
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
Methods
get_err_msg
Return a multi-line error message for being printed, in the following format. Attributes
args
column
Position within the line in the MOF file or MOF string where the error occurred (1-based). conn_id
Connection ID of the connection in whose context the error happened. conn_str
String that identifies the connection in exception messages. context
MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the ‘^’ character to indicate the position of the token in error in the MOF line. file
File name of the MOF file where the error occurred. lineno
Line number in the MOF file or MOF string where the error occurred (1-based). message
msg
Brief description of the problem. Details
-
column
¶ Position within the line in the MOF file or MOF string where the error occurred (1-based).
Type: integer
-
file
¶ File name of the MOF file where the error occurred.
None if the error occurred in a MOF string that was compiled.
Type: string
-
context
¶ MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the ‘^’ character to indicate the position of the token in error in the MOF line.
Type: string
-
get_err_msg
()[source]¶ Return a multi-line error message for being printed, in the following format. The text in angle brackets refers to the same-named properties of the exception instance:
Syntax error:<file>:<lineno>: <msg> <context - MOF line> <context - position indicator line>
Returns: Multi-line error message. Return type: string
- parser_token – PLY parser token for the error (that is, the
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:
-
A MOF compiler that takes MOF files as input and updates the CIM repository of a WBEM server with the result.
-
A WBEM client in the form of a shell that provides an interactive Python environment for issuing WBEM operations to a WBEM server.
mof_compiler¶
The mof_compiler
command compiles MOF files and updates the CIM repository
of a WBEM server with the result.
If the compiler fails, any changes made to the CIM repository in the WBEM server as part of the current compilation are rolled back. A limitation is that changes to qualifier declarations are not yet rolled back (see issue #990).
The compiler provides a dry-run mode that simulates the compilation but does not change the CIM repository in the WBEM server.
Here is the help text of the command:
usage: mof_compiler [options] moffile ...
Compile MOF files, and update a namespace in a WBEM server with the result.
Positional arguments:
moffile Path name of the MOF file to be compiled.
Can be specified multiple times.
Server related options:
Specify the WBEM server and namespace the MOF compiler works against, 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 Removal mode: Remove elements (found in the MOF files)
from the WBEM server's namespace, instead of creating
or updating them
-d, --dry-run Dry-run mode: Don't actually modify the WBEM server's
namespace, just check MOF syntax. Connection to WBEM
server is still required to check qualifiers.
General options:
-I dir, --include dir
Path name of a MOF include directory. Can be specified
multiple times.
-v, --verbose Print more messages while processing
-V, --version Display pywbem version and exit.
-h, --help Show this help message and exit
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 in the form of a shell that provides
an interactive Python environment for issuing WBEM operations to a WBEM
server.
See Python functions in wbemcli for details on the Python functions available in that environment.
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
-V, --version Display pywbem version and exit.
--statistics Enable gathering of statistics on operations.
--mock-server [file name [file name ...]]
Activate pywbem_mock in place of a live WBEMConnection
and compile/build the files defined (".mof" suffix or
"py" suffix. MOF files are compiled and python files
are executed assuming that they include mock_pywbem
methods that add objects to the repository.
-l log_spec[,logspec], --log log_spec[,logspec]
Log_spec defines characteristics of the various named
loggers. It is the form:
COMP=[DEST[:DETAIL]] where:
COMP: Logger component name:[api|http|all].
(Default=all)
DEST: Destination for component:[file|stderr].
(Default=file)
DETAIL: Detail Level to log: [all|paths|summary] or
an integer that defines the maximum length of
of each log record.
(Default=all)
-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)
Python functions in wbemcli¶
The interactive shell of wbemcli provides Python functions for the WBEM operations, and some functions for help display and debugging:
Function | WBEM operation |
---|---|
ei() |
EnumerateInstances |
ein() |
EnumerateInstanceNames |
gi() |
GetInstance |
mi() |
ModifyInstance |
ci() |
CreateInstance |
di() |
DeleteInstance |
a() |
Associators |
an() |
AssociatorNames |
r() |
References |
rn() |
ReferenceNames |
im() |
InvokeMethod |
eqy() |
ExecQuery |
iei() |
IterEnumerateInstances (pywbem only) |
ieip() |
IterEnumerateInstancePaths (pywbem only) |
iai() |
IterAssociatorInstances (pywbem only) |
iaip() |
IterAssociatorInstancePaths (pywbem only) |
iri() |
IterReferenceInstances (pywbem only) |
irip() |
IterReferenceInstancePaths (pywbem only) |
iqi() |
IterQueryInstances (pywbem only) |
oei() |
OpenEnumerateInstances |
oeip() |
OpenEnumerateInstancePaths |
oai() |
OpenAssociatorInstances |
oaip() |
OpenAssociatorInstancePaths |
ori() |
OpenReferenceInstances |
orip() |
OpenReferenceInstancePaths |
oqi() |
OpenQueryInstances |
piwp() |
PullInstancesWithPath |
pip() |
PullInstancePaths |
pi() |
PullInstances |
ce() |
CloseEnumeration |
ec() |
EnumerateClasses |
ecn() |
EnumerateClassNames |
gc() |
GetClass |
mc() |
ModifyClass |
cc() |
CreateClass |
dc() |
DeleteClass |
eq() |
EnumerateQualifiers |
gq() |
GetQualifier |
sq() |
SetQualifier |
dq() |
DeleteQualifier |
h() |
Print help text for interactive environment |
pdb() |
Run a statement under the PDB debugger |
pp() |
Alias for pprint() |
The interactive Python environment of the wbemcli
command has wbemcli
as its current Python namespace, so the functions shown below can directly be
invoked (e.g. ei(...)
).
-
wbemcli.
ei
(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None)[source]¶ This function is a wrapper for
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.
None will cause the server default of True to be used.
Deprecated in DSP0200: WBEM server implementations for True may vary; this parameter should be set to False by the caller.
- 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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. 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
- cn (string or
-
wbemcli.
ein
(cn, ns=None)[source]¶ This function is a wrapper for
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
- cn (string or
-
wbemcli.
gi
(ip, lo=None, iq=None, ico=None, pl=None)[source]¶ This function is a wrapper for
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.
None will cause the server default of True to be used.
Deprecated in DSP0200: WBEM server implementations for True may vary; this parameter should be set to False by the caller.
- iq (
bool
) –IncludeQualifiers flag: Include qualifiers.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instance.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. 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: - ip (
-
wbemcli.
mi
(mi, iq=None, pl=None)[source]¶ This function is a wrapper for
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.
None will cause the server default of True to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be modified by this operation.
- pl (string or iterable of string) – PropertyList: Names of properties to be modified. An empty iterable indicates to modify no properties. If None, all properties exposed by the instance will be modified.
- mi (
-
wbemcli.
ci
(ni, ns=None)[source]¶ This function is a wrapper for
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.
Instance-level qualifiers have been deprecated in CIM, so any qualifier values specified using the qualifiers attribute of this object will be ignored.
- 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 of the new instance, 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: - ni (
-
wbemcli.
di
(ip)[source]¶ This function is a wrapper for
DeleteInstance()
.Delete an instance.
Parameters: ip ( CIMInstanceName
) –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.
-
wbemcli.
a
(op, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None)[source]¶ This function is a wrapper for
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) –
AssocClass 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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances or for the properties and methods in the retrieved classes.
None will cause the server default of False to be used.
Deprecated in DSP0200 for instance-level use: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
Returns: - For instance-level use, a list of
CIMInstance
objects representing the retrieved instances, with their path attribute being aCIMInstanceName
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 retrieved 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.
- classpath (
Return type: list of result objects
- op (
-
wbemcli.
an
(op, ac=None, rc=None, r=None, rr=None)[source]¶ This function is a wrapper for
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) –
AssocClass 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 retrieved 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 retrieved 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 result objects
- op (
-
wbemcli.
r
(op, rc=None, r=None, iq=None, ico=None, pl=None)[source]¶ This function is a wrapper for
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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances or for the properties and methods in the retrieved classes.
None will cause the server default of False to be used.
Deprecated in DSP0200 for instance-level use: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
Returns: - For instance-level use, a list of
CIMInstance
objects representing the retrieved instances, with their path attribute being aCIMInstanceName
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 retrieved 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.
- classpath (
Return type: list of result objects
- op (
-
wbemcli.
rn
(op, rc=None, r=None)[source]¶ This function is a wrapper for
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 retrieved 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 retrieved 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 result objects
- op (
-
wbemcli.
im
(mn, op, params, **kwparams)[source]¶ This function is a wrapper for
InvokeMethod()
.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.
Parameters: - mn (string) – Method name.
- op (
CIMClassName
) – Target instance path. - op – Target class path.
- params (iterable) –
Input parameters for the method.
Each item in the iterable is a single parameter value and can be any of:
CIMParameter
representing a parameter value. The name, value, type and embedded_object attributes of this object are used.- tuple of name, value, with:
- name (string): Parameter name (case independent)
- value (CIM data type): Parameter value
- **kwparams (named/keyword arguments) –
Input parameters for the method.
- key (string): Parameter name (case independent)
- value (CIM data type): Parameter value
Returns: - rv (CIM data type): Return value of the CIM method.
- out (NocaseDict):
Dictionary with all provided output parameters of the CIM method,
with:
- key (unicode string): Parameter name
- value (CIM data type): Parameter value
Return type: tuple(rv, out), with these tuple items
-
wbemcli.
eqy
(ql, qs, ns=None)[source]¶ New in pywbem 0.12
This function is a wrapper for
ExecQuery()
.Execute a query in a namespace.
Parameters: - ql (string) – Name of the query language used in the qs parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. Because this is not a filter query, “DMTF:FQL” is not a valid query language for this request.
- qs (string) – Query string in the query language specified in 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.
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.
-
wbemcli.
iei
(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None, fl=None, fs=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterEnumerateInstances()
.Enumerate the instances of a class (including instances of its subclasses) in a namespace, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
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.
None will cause the server default of True to be used.
Deprecated in DSP0200: WBEM server implementations for True may vary; this parameter should be set to False by the caller.
- 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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be included.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: A generator object that iterates the resulting CIM instances. These instances include an instance path that has its host and namespace components set.
Return type: generator iterating
CIMInstance
- cn (string or
-
wbemcli.
ieip
(cn, ns=None, fl=None, fs=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterEnumerateInstancePaths()
.Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
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.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: A generator object that iterates the resulting CIM instance paths. These instance paths have their host and namespace components set.
Return type: generator iterating
CIMInstanceName
- cn (string or
-
wbemcli.
iai
(ip, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None, fl=None, fs=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterAssociatorInstances()
.Retrieve the instances associated to a source instance, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
Parameters: - ip (
CIMInstanceName
) – Source instance path. - ac (string) –
AssocClass 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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be included.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: A generator object that iterates the resulting CIM instances. These instances include an instance path that has its host and namespace components set.
Return type: generator iterating
CIMInstance
- ip (
-
wbemcli.
iaip
(ip, ac=None, rc=None, r=None, rr=None, fl=None, fs=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterAssociatorInstancePaths()
.Retrieve the instance paths of the instances associated to a source instance, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
Parameters: - ip (
CIMInstanceName
) – Source instance path. - ac (string) –
AssocClass 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.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: A generator object that iterates the resulting CIM instance paths. These instance paths have their host and namespace components set.
Return type: generator iterating
CIMInstanceName
- ip (
-
wbemcli.
iri
(ip, rc=None, r=None, iq=None, ico=None, pl=None, fl=None, fs=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterReferenceInstances()
.Retrieve the association instances that reference a source instance, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
Parameters: - ip (
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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be included.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: A generator object that iterates the resulting CIM instances. These instances include an instance path that has its host and namespace components set.
Return type: generator iterating
CIMInstance
- ip (
-
wbemcli.
irip
(ip, rc=None, r=None, fl=None, fs=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterReferenceInstancePaths()
.Retrieve the instance paths of the association instances that reference a source instance, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
Parameters: - ip (
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 fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: A generator object that iterates the resulting CIM instance paths. These instance paths have their host and namespace components set.
Return type: generator iterating
CIMInstanceName
- ip (
-
wbemcli.
iqi
(ql, qs, ns=None, rc=None, ot=None, coe=None, moc=1000)[source]¶ New in pywbem 0.10 as experimental and finalized in 0.12.
This function is a wrapper for
IterQueryInstances()
.Execute a query in a namespace, using the corresponding pull operations if supported by the WBEM server or otherwise the corresponding traditional operation, and using the Python generator idiom to return the result.
This method is an alternative to using the pull operations directly, that frees the user of having to know whether the WBEM server supports pull operations.
Other than the other i…() functions, this function does not return a generator object directly, but as a property of the returned object.
Parameters: - ql (string) – Name of the query language used in the qs parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. Because this is not a filter query, “DMTF:FQL” is not a valid query language for this request.
- qs (string) – Query string in the query language specified in 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 class definition describing the properties of the returned instances will be returned.
None will cause the server to use its default of False.
- ot (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of instances the WBEM server may return for each of the open and pull requests issued during the iterations over the returned generator object.
Zero and None are not allowed.
Returns: An object with the following properties:
query_result_class (
CIMClass
):The query result class, if requested via the rc parameter.
None, if a query result class was not requested.
generator (generator iterating
CIMInstance
):A generator object that iterates the CIM instances representing the query result. These instances do not have an instance path set.
Return type: IterQueryInstancesReturn
-
wbemcli.
oei
(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None, fl=None, fs=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenEnumerateInstances()
.Open an enumeration session to enumerate the instances of a class (including instances of its subclasses) in a namespace.
Use the
piwp()
function to retrieve the next set of instances or thece()
function to close the enumeration session before it is complete.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.
None will cause the server default of True to be used.
Deprecated in DSP0200: WBEM server implementations for True may vary; this parameter should be set to False by the caller.
- 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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- instances (list of
CIMInstance
): The retrieved instances. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- cn (string or
-
wbemcli.
oeip
(cn, ns=None, fl=None, fs=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenEnumerateInstancePaths()
.Open an enumeration session to enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.
Use the
pip()
function to retrieve the next set of instance paths or thece()
function to close the enumeration session before it is complete.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.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- paths (list of
CIMInstanceName
): The retrieved instance paths. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- cn (string or
-
wbemcli.
oai
(ip, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None, fl=None, fs=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenAssociatorInstances()
.Open an enumeration session to retrieve the instances associated to a source instance.
Use the
piwp()
function to retrieve the next set of instances or thece()
function to close the enumeration session before it is complete.Parameters: - ip (
CIMInstanceName
) – Source instance path. - ac (string) –
AssocClass 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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- instances (list of
CIMInstance
): The retrieved instances. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ip (
-
wbemcli.
oaip
(ip, ac=None, rc=None, r=None, rr=None, fl=None, fs=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenAssociatorInstancePaths()
.Open an enumeration session to retrieve the instance paths of the instances associated to a source instance.
Use the
pip()
function to retrieve the next set of instance paths or thece()
function to close the enumeration session before it is complete.Parameters: - ip (
CIMInstanceName
) – Source instance path. - ac (string) –
AssocClass 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.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- paths (list of
CIMInstanceName
): The retrieved instance paths. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ip (
-
wbemcli.
ori
(ip, rc=None, r=None, iq=None, ico=None, pl=None, fl=None, fs=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenReferenceInstances()
.Open an enumeration session to retrieve the association instances that reference a source instance.
Use the
piwp()
function to retrieve the next set of instances or thece()
function to close the enumeration session before it is complete.Parameters: - ip (
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.
None will cause the server default of False to be used.
Deprecated in DSP0200: Clients cannot rely on qualifiers to be returned in this operation.
- ico (
bool
) –IncludeClassOrigin flag: Include class origin information for the properties in the retrieved instances.
None will cause the server default of False to be used.
Deprecated in DSP0200: WBEM servers may either implement this parameter as specified, or may treat any specified value as False.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- instances (list of
CIMInstance
): The retrieved instances. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ip (
-
wbemcli.
orip
(ip, rc=None, r=None, fl=None, fs=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenReferenceInstancePaths()
.Open an enumeration session to retrieve the instance paths of the association instances that reference a source instance.
Use the
pip()
function to retrieve the next set of instance paths or thece()
function to close the enumeration session before it is complete.Parameters: - ip (
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 fs parameter. The DMTF-defined Filter Query Language (see DSP0212) is specified as “DMTF:FQL”.
None means that no such filtering is peformed.
- fs (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 (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- paths (list of
CIMInstanceName
): The retrieved instance paths. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ip (
-
wbemcli.
oqi
(ql, qs, ns=None, rc=None, ot=None, coe=None, moc=None)[source]¶ This function is a wrapper for
OpenQueryInstances()
.Open an enumeration session to execute a query in a namespace and to retrieve the instances representing the query result.
Use the
pi()
function to retrieve the next set of instances or thece()
function to close the enumeration session before it is complete.Parameters: - ql (string) – Filter query language to be used for the filter defined in the q parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. Because this is not a filter query, “DMTF:FQL” is not a valid query language for this request.
- qs (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 class definition describing the properties of the returned instances will be returned.
None will cause the server to use its default of False.
- ot (
Uint32
) –Operation timeout in seconds. This is the minimum time the WBEM server must keep the enumeration session open between requests on that session.
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 (
Uint32
) –Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: A
namedtuple()
object containing the following named items:- instances (list of
CIMInstance
): The retrieved instances. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session. - query_result_class (
CIMClass
): Result class definition describing the properties of the returned instances if requested, or otherwise None.
-
wbemcli.
piwp
(ec, moc)[source]¶ This function is a wrapper for
PullInstancesWithPath()
.Retrieve the next set of instances from an open enumeration session. The retrieved instances include their instance paths.
This operation can only be used on enumeration sessions that have been opened by one of the following functions:
Parameters: - ec (
tuple()
of server_context, namespace) – A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session. - moc (
Uint32
) –Maximum number of objects to return for this operation.
None is not allowed.
Returns: A
namedtuple()
object containing the following named items:- instances (list of
CIMInstance
): The retrieved instances. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ec (
-
wbemcli.
pip
(ec, moc)[source]¶ This function is a wrapper for
PullInstancePaths()
.Retrieve the next set of instance paths from an open enumeration session.
This operation can only be used on enumeration sessions that have been opened by one of the following functions:
Parameters: - ec (
tuple()
of server_context, namespace) – A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session. - moc (
Uint32
) –Maximum number of objects to return for this operation.
None is not allowed.
Returns: A
namedtuple()
object containing the following named items:- paths (list of
CIMInstanceName
): The retrieved instance paths. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ec (
-
wbemcli.
pi
(ec, moc)[source]¶ This function is a wrapper for
PullInstances()
.Retrieve the next set of instances from an open enumeration session. The retrieved instances do not include an instance path.
This operation can only be used on enumeration sessions that have been opened by one of the following functions:
Parameters: - ec (
tuple()
of server_context, namespace) – A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session. - moc (
Uint32
) –Maximum number of objects to return for this operation.
None is not allowed.
Returns: A
namedtuple()
object containing the following named items:- instances (list of
CIMInstance
): The retrieved instances. - eos (
bool
): True if the enumeration session is exhausted after this operation. Otherwise eos is False and the context item is the context object for the next operation on the enumeration session. - context (
tuple()
of server_context, namespace): A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must be supplied with the next pull or close operation for this enumeration session.
- ec (
-
wbemcli.
ce
(ec)[source]¶ This function is a wrapper for
CloseEnumeration()
.Close an open enumeration session, causing an early termination of an incomplete enumeration session.
The enumeration session must still be open when this operation is performed.
Parameters: ec ( tuple()
of server_context, namespace) – A context object identifying the open enumeration session, including its current enumeration state, and the namespace. This object must have been returned by the previous open or pull operation for this enumeration session.
-
wbemcli.
ec
(ns=None, cn=None, di=None, lo=None, iq=None, ico=None)[source]¶ This function is a wrapper for
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 information for properties and methods in the retrieved class.
None will cause the server default of False to be used.
Returns: The enumerated classes.
Return type: list of
CIMClass
- ns (string) –
-
wbemcli.
ecn
(ns=None, cn=None, di=None)[source]¶ This function is a wrapper for
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 unicode string
- ns (string) –
-
wbemcli.
gc
(cn, ns=None, lo=None, iq=None, ico=None, pl=None)[source]¶ This function is a wrapper for
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 information for properties and methods in the retrieved class.
None will cause the server default of False to be used.
- pl (string or iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). An empty iterable indicates to include no properties. If None, all properties will be included.
Returns: The retrieved class.
Return type: - cn (string or
-
wbemcli.
mc
(mc, ns=None)[source]¶ This function is a wrapper for
ModifyClass()
.Modify a class.
Parameters:
-
wbemcli.
cc
(nc, ns=None)[source]¶ This function is a wrapper for
CreateClass()
.Create a class in a namespace.
Parameters:
-
wbemcli.
dc
(cn, ns=None)[source]¶ This function is a wrapper for
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.
- cn (string or
-
wbemcli.
eq
(ns=None)[source]¶ This function is a wrapper for
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]¶ This function is a wrapper for
GetQualifier()
.Retrieve a qualifier type (= declaration).
Parameters: Returns: The retrieved qualifier type.
Return type:
-
wbemcli.
sq
(qd, ns=None)[source]¶ This function is a wrapper for
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.
- qd (
-
wbemcli.
dq
(qn, ns=None)[source]¶ This function is a wrapper for
DeleteQualifier()
.Delete a qualifier type (= declaration).
Parameters:
Mock support¶
Experimental: New in pywbem 0.12.0 as experimental.
Overview¶
The pywbem package contains the pywbem_mock
subpackage which provides mock
support that enables usage of the pywbem library without a WBEM server.
This subpackage is used for testing the pywbem library itself and can be used
for the development and testing of Python programs that use the pywbem library.
The pywbem mock support contains the pywbem_mock.FakedWBEMConnection
class that establishes a faked connection. That class is a subclass of
pywbem.WBEMConnection
and replaces its internal methods that use
HTTP/HTTPS to communicate with a WBEM server with methods that instead operate
on a local in-memory repository of CIM objects (the mock repository).
As a result, the operation methods of FakedWBEMConnection
are those inherited from WBEMConnection
, so they have the
exact same input parameters, output parameters, return values, and even most of
the raised exceptions, as when being invoked on a
WBEMConnection
object against a WBEM server.
Each FakedWBEMConnection
object has its own mock
repository.
The mock repository contains the same kinds of CIM objects a WBEM server
repository contains: CIM classes, CIM instances, and CIM qualifier types
(declarations), all contained in CIM namespaces.
Because FakedWBEMConnection
operates only on the mock
repository, the class does not have any connection- or security-related
constructor parameters.
Like WBEMConnection
, FakedWBEMConnection
has a default CIM namespace that can be set upon object creation.
FakedWBEMConnection
has some additional methods that
provide for adding CIM classes, instances and qualifier types to its mock
repository. See Building the mock repository for details.
There are no setup methods to remove or modify CIM objects in the mock
repository. However, if needed, that can be done by using operation methods
such as DeleteClass()
or
ModifyInstance()
.
The mock repository supports two operation modes:
- full mode: The repository must contain the classes and qualifier types that are needed for the operations that are invoked. This results in a behavior of the faked operations that is close to the behavior of the operations of a real WBEM server.
- lite mode: The repository does not need to contain any classes and qualifier types, and can be used when it contains only instances. This simplifies the setup of the mock repository for users, but it also affects the behavior of the faked instance operations to be farther away from the behavior of the operations of a real WBEM server. For example, the faked EnumerateInstances operation will not return instances of subclasses when DeepInheritance is set, because without looking at classes, there is no way it can find out what the subclasses are. And of course, class operations and qualifier operations that retrieve objects don’t work at all if the mock repository does not contain them.
The operation mode of the mock repository is selected when creating
a FakedWBEMConnection
object, through its repo_lite
init parameter. Full mode is the default.
The following example demonstrates setting up a faked connection, adding several CIM objects defined in a MOF string to its mock repository, and executing WBEM operations on the faked connection:
import pywbem
import pywbem_mock
# MOF string defining qualifiers, class, and instance
mof = '''
Qualifier Key : boolean = false,
Scope(property, reference),
Flavor(DisableOverride, ToSubclass);
Qualifier Description : string = null,
Scope(any),
Flavor(EnableOverride, ToSubclass, Translatable);
Qualifier In : boolean = true,
Scope(parameter),
Flavor(DisableOverride, ToSubclass);
[Description ("This is a dumb test class")]
class CIM_Foo {
[Key, Description ("This is key prop")]
string InstanceID;
[Description ("This is some simplistic data")]
Uint32 SomeData;
[Description ("This is a method without parameters")]
string Fuzzy();
[Description ("This is a second method with parameter")]
uint32 Delete([IN, Description('blahblah']
boolean Immediate);
};
instance of CIM_Foo as $I1 { InstanceID = "I1"; SomeData=3 };
'''
# Create a faked connection (with a mock repository in full mode)
conn = pywbem_mock.FakedWBEMConnection(default_namespace='root/cimv2')
# Compile the MOF string and add its CIM objects to the default namespace
# of the mock repository
conn.compile_mof_string(mof)
# Perform a few operations on the faked connection:
# Enumerate top-level classes in the default namespace (without subclasses)
classes = conn.EnumerateClasses();
for cls in classes:
print(cls.tomof())
# Get the 'Description' qualifier type in the default namespace
qd = conn.GetQualifier('Description')
# Enumerate subclasses of 'CIM_Foo' in the default namespace (without subclasses)
classes2 = conn.EnumerateClasses(classname='CIM_Foo')
# Get 'CIM_Foo' class in the default namespace
my_class = conn.GetClass('CIM_Foo')
# Get a specific instance of 'CIM_Foo' in the default namespace
inst = conn.GetInstance(CIMInstanceName('CIM_Foo', {'InstanceID': "I1"})
Pywbem mock supports:
- All of the
WBEMConnection
operation methods that communicate with the WBEM server (see below for list of operations supported and their limitations). - Multiple CIM namespaces and a default namespace on the faked connection.
- Gathering time statistics and delaying responses for a predetermined time.
WBEMConnection
logging except that there are no HTTP entries in the log.
Pywbem mock does NOT support:
- CIM-XML protocol security and security constructor parameters of
WBEMConnection
. - Dynamic WBEM server providers in that the data for responses is from the
mock repository that is built before the request rather than from resources
accessed by such providers. This means there is no dynamic determination of
property values for newly created CIM instances. Therefore, creating CIM
instances requires that all keybinding values as well as all other property
values must be provided as input to the
CreateInstance()
operation by the user. - Processing of queries defined for
ExecQuery()
in languages like CQL and WQL. The mocked operation parses only the very general portions of the query for class/instance name and properties. - Filter processing of the FQL (see DSP0212) Filter Query Language parameter QueryFilter used by the Open… operations because it does not implement the parser/processor for the FQL language. It returns the same data as if the filter did not exist.
- Providing data in the trace variables for last request and last reply in
WBEMConnection
: last_request, last_raw_request, last_reply, last_raw_reply, last_request_len, or last_reply_len. - Log entries for HTTP request and response in the logging support of
WBEMConnection
, because it does not actually build the HTTP requests or responses. - Generating CIM indications.
- Some of the functionality that may be implemented in real WBEM servers such as the __Namespace__ class/provider or the CIM_Namespace class/provider, because these are WBEM server-specific implementations and not WBEM request level capabilities. Note that such capabilities can be at least partly built on top of the existing capabilities by inserting corresponding CIM instances into the mock repository.
Faked WBEM operations¶
The pywbem_mock.FakedWBEMConnection
class supports the same WBEM
operations that are supported by the pywbem.WBEMConnection
class.
These faked operations generally adhere to the behavior requirements defined in DSP0200 for handling input parameters and returning a result.
The faked operations get the data to be returned from the mock repository of the faked connection, and put the data provided in operation parameters that modify objects (create, modify, and delete operations) into that mock repository.
However, because the pywbem mock support is only a simulation of a WBEM server and intended to be used primarily for testing, there are a number of limitations and differences between the behavior of the faked operations and a real WBEM server.
The descriptions below describe differences between the faked operations of the pywbem mock support and the operations of a real WBEM server, and the effects of the operation modes of the mock repository.
Faked instance operations¶
Instance operations work in both operation modes of the repository.
The operations that retrieve objects require instances in the repository for the instances to be recovered. We allow some of these methods to try to return data if the class repository is empty but they may react differently if there are classes in the repository.
- GetInstance: Behaves like
GetInstance()
, except that the behavior of property selection for the returned instance when LocalOnly is set depends on the operation mode of the mock repository: In lite mode, property selection is based upon the class_origin attribute of the properties of the instance. In full mode, property selection is based upon the classes in which they are defined. - EnumerateInstances: Behaves like
EnumerateInstances()
, except for these differences when the mock repository is in lite mode: When DeepInheritance is set, instances of subclasses of the specified class will not be returned, and LocalOnly is ignored and treated as if it was set to False. - EnumerateInstanceNames: Behaves like
EnumerateInstances()
, except for this difference when the mock repository is in lite mode: When DeepInheritance is set, instances of subclasses of the specified class will not be returned. - CreateInstance: Behaves like
CreateInstance()
, except for these differences: This operation requires that all key properties are specified in the new instance since the mock repository has no support for dynamically setting key properties as a dynamic provider for the class in a real WBEM server might have. This operation requires that the mock repository is in full mode and that the class of the new instance exists in the mock repository. It fails with not supported if the mock repository is in lite mode. - ModifyInstance: Behaves like
ModifyInstance()
. This operation requires that the mock repository is in full mode and that the class of the instance exists in the mock repository. It fails with not supported if the mock repository is in lite mode. - DeleteInstance: Behaves like
DeleteInstance()
, except for this difference depending on the operation mode of the mock repository: In lite mode, the operation does not check for existence of the class of the instance. In full mode, the operation validates the existence of the class of the instance. In the current implementation, this operation does not check for association instances referencing the instance to be deleted, so any such instances become dangling references. - ExecQuery: This operation is not currently implemented. Once implemented:
Behaves like
ExecQuery()
, except that it returns instances based on a very limited parsing of the query string: Generally, the SELECT and FROM clauses are evaluated, and the WHERE clause is ignored. The query string is not validated for correctness. The query language is not validated.
Faked association operations¶
The faked association operations support both instance-level use and class-level use. Class-level use requires the mock repository to be in full mode, while instance-level use works in both operation modes of the mock repository.
- AssociatorNames: Behaves like
AssociatorNames()
, with the following exceptions and requirements: For class-level use, the mock repository must be in full mode and the source, target, and association classes and their subclasses must exist in the mock repository. For instance-level use, correct results are returned if the mock repository is in full mode and the the source, target, and association classes and their subclasses exist in the repository. More limited results are returned in lite mode, because the class hierarchy is not considered when selecting the instances to be returned. - Associators: Behaves like
Associators()
, with the exceptions and requirements described for AssociatorNames, above. - ReferenceNames: Behaves like
ReferenceNames()
, with the exceptions and requirements described for AssociatorNames, above. - References: Behaves like
References()
, with the exceptions and requirements described for AssociatorNames, above.
Faked method invocation operation¶
The faked method invocation operation (InvokeMethod) behaves like
InvokeMethod()
, but because of the nature of
InvokeMethod, the user must provide a callback function that performs the
actual task of the CIM method. The mock repository must be in full operation
mode.
The callback function must have the signature defined in the
method_callback_interface()
function and must be registered
with the mock repository through
add_method_callback()
for a particular
combination of namespace, class, and CIM method name.
When the callback function is invoked on behalf of an InvokeMethod operation, the target object of the method invocation (class or instance) is provided to the callback function, in addition to the method input parameters.
The callback function can access the mock repository of the faked connection using the normal WBEM operation methods.
The callback function is expected to return a tuple consisting of two items:
- the CIM method return value, as a CIM data type value.
- a NocaseDict containing any output parameters as
CIMParameter
objects.
The following is an example for invoking the faked InvokeMethod operation with a simple callback function.
import pywbem
import pywbem_mock
def method1_callback(conn, methodname, objectname, **params):
"""
Callback function that demonstrates what can be done, without being
really useful.
"""
print('params: %r' % params )
print('object_name %s' % objectname)
# Access input parameters
ip1 = params['IP1']
# Access the mock repository through the faked connection object.
# In case of a static CIM method, objectname is a
:class:`~pywbem.CIMClassName` object.
cl = conn.GetClass(objectname)
# Set return value and output parameters
rtn_val = 0
op1 = CIMParameter('OP1', 'string', value='Some output data')
return rtn_val, [op1]
mof = '''
Qualifier In : boolean = true,
Scope(parameter),
Flavor(DisableOverride, ToSubclass);
Qualifier Key : boolean = false,
Scope(property, reference),
Flavor(DisableOverride, ToSubclass);
Qualifier Out : boolean = false,
Scope(parameter),
Flavor(DisableOverride, ToSubclass);
Qualifier Static : boolean = false,
Scope(property, method),
Flavor(DisableOverride, ToSubclass);
class TST_Class {
string InstanceID;
[Static,
Description("Static method with input and output parameters")]
uint32 Method1(
[IN, Description("Input param 1")]
string IP1,
[IN (false), OUT, Description("Output param 1")]
string OP1);
};
'''
# Create a faked connection
conn = pywbem_mock.FakedWBEMConnection(default_namespace='root/cimv2')
# Compile the MOF string and add its CIM objects to the default namespace
# of the mock repository
conn.compile_mof_string(mof)
# Register the method callback function to the mock repository, for the
# default namespace of the connection
conn.add_method_callback('TST_Class', 'Method1', method1_callback)
# Invoke static method Method1
params = [('IP1', 'someData')]
result = conn.InvokeMethod('Method1', 'TST_Class', Params=params)
print('Return value: %r' % result[0])
print('Output parameters: %r' % (result[1],))
Callback functions for faked method invocation¶
The callback functions for faked method invocation must have the following signature:
-
pywbem_mock.
method_callback_interface
(conn, methodname, objectname, **params)[source]¶ Interface for user-provided callback functions for CIM method invocation on a faked connection.
Experimental: New in pywbem 0.12 as experimental.
Parameters: - conn (
FakedWBEMConnection
) – Faked connection. This can be used to access the mock repository of the faked connection, via its operation methods (e.g. GetClass). - methodname (string) – The CIM method name that is being invoked. This is the method name for which the callback function was registered. This parameter allows a single callback function to be registered for multiple methods.
- objectname (
CIMInstanceName
orCIMClassName
) –The object path of the target object of the invoked method, as follows:
- Instance-level call: The instance path of the target instance, as a
CIMInstanceName
object which has its namespace property set to the target namespace of the invocation. Its host property will not be set. - Class-level call: The class path of the target class, as a
CIMClassName
object which has its namespace property set to the target namespace of the invocation. Its host property will not be set.
- Instance-level call: The instance path of the target instance, as a
- params (NocaseDict) –
The input parameters for the method that were passed to the InvokeMethod operation.
Each dictionary item represents a single input parameter for the CIM method and is a
CIMParameter
object, regardless of how the input parameter was passed to theInvokeMethod()
method.The
CIMParameter
object will have at least the following properties set:- name (string): Parameter name (case independent).
- type (string): CIM data type of the parameter.
- value (CIM data type): Parameter value.
Returns: The callback function must return a tuple consisting of:
return_value (CIM data type): Return value for the CIM method.
out_params (iterable of
CIMParameter
):Each item represents a single output parameter of the CIM method. The
CIMParameter
objects must have at least the following properties set:- name (string): Parameter name (case independent).
- type (string): CIM data type of the parameter.
- value (CIM data type): Parameter value.
Return type: Raises: Since the callback function mocks a CIM method invocation, it should raise
CIMError
exceptions to indicate failures. Any other exceptions raised by the callback function will be mapped toCIMError
exceptions with status CIM_ERR_FAILED and a message that contains information about the exception including a traceback.- conn (
Faked pull operations¶
The faked pull operations behave like the pull operations of
WBEMConnection
, with the following exceptions:
- The filter query related parameters FilterQuery and FilterQueryLanguage are ignored and no such filtering takes place.
- The ContinueOnError parameter is ignored because injecting an error into the processing of the pull operations is not supported by the pywbem mock support, so no failures can happen during the processing of the pull operations.
- The OperationTimeout parameter is currently ignored. As a result, there
will be no timeout if the
response_delay
property is set to a time larger than the OperationTimeout parameter.
The faked pull operations are:
- OpenEnumerateInstances: Behaves like
OpenEnumerateInstances()
, with the stated exceptions. - OpenEnumerateInstancePaths: Behaves like
OpenEnumerateInstancePaths()
, with the stated exceptions. - OpenAssociatorInstances: Behaves like
OpenAssociatorInstances()
, with the stated exceptions. - OpenAssociatorInstancePaths: Behaves like
OpenAssociatorInstancePaths()
, with the stated exceptions. - OpenReferenceInstances: Behaves like
OpenReferenceInstances()
, with the stated exceptions. - OpenReferenceInstancePaths: Behaves like
OpenReferenceInstancePaths()
, with the stated exceptions. - OpenQueryInstances: Behaves like
OpenQueryInstances()
, with the stated exceptions. - PullInstancesWithPath: Behaves like
PullInstancesWithPath()
, with the stated exceptions. - PullInstancePaths: Behaves like
PullInstancePaths()
, with the stated exceptions. - PullInstances: Behaves like
PullInstances()
, with the stated exceptions. - CloseEnumeration: Behaves like
CloseEnumeration()
, with the stated exceptions.
Faked iter operations¶
The iter operations on a faked connection are in fact the iter operations
on WBEMConnection
, because they do not directly issue requests
and responses on the connection, but instead are simply a layer on top of
underlying operations. For example, IterEnumerateInstances
invokes either pull operations (i.e. OpenEnumerateInstances followed by
PullInstancesWithPath) or traditional operations (i.e. EnumerateInstances).
The use of pull vs. traditional operations is controlled via the
use_pull_operations init parameter of
FakedWBEMConnection
.
The iter operations are:
Faked class operations¶
Class operations only work if the mock repository is in full operation mode.
- GetClass: Behaves like
GetClass()
. Requires that the class to be returned is in the mock repository. - EnumerateClasses: Behaves like
EnumerateClasses()
. Requires that the class specified in the ClassName parameter as well as the classes to be returned are in the mock repository. - EnumerateClassNames: Behaves like
EnumerateClassNames()
. Requires that the class specified in the ClassName parameter as well as the classes to be returned are in the mock repository. - CreateClass: Behaves like
CreateClass()
. Requires that the superclass of the new class (if it specifies one) is in the mock repository. - DeleteClass: Behaves like
DeleteClass()
, with the following difference: This operation additionally deletes all direct and indirect subclasses of the class to be deleted, and all instances of the classes that are being deleted. Requires that the class to be deleted is in the mock repository. - ModifyClass: Not currently implemented.
Faked qualifier operations¶
Qualifier operations only work if the mock repository is in full operation mode.
- SetQualifier: Behaves like
SetQualifier()
. Requires that the specified qualifier type is in the mock repository. - GetQualifier: Behaves like
GetQualifier()
. Requires that the specified qualifier type is in the mock repository. - EnumerateQualifiers: Behaves like
EnumerateQualifiers()
. Requires that the qualifier types to be returned are in the mock repository.
Building the mock repository¶
The mock repository should contain the CIM qualifier declarations, CIM classes, CIM instances, and CIM methods to be used in the mock environment. The mock user creates a repository that contains the CIM objects required for the operations to be executed in the mock environment. Thus, if the user only requires CIM_ComputerSystem, only that class and its dependent classes need be in the repository along with instances of the classes that will satisfy the methods called
FakedWBEMConnection
and
DMTFCIMSchema
provide the tools to build the mock
repository.
There are two ways to build a mock repository:
Directly from pywbem CIM objects (
CIMClass
,CIMInstance
, etc). Seeadd_cimobjects()
From MOF definitions of the objects (which can be a string or a file, in and with MOF pragma include statements).
There are two methods to help building the repository from MOF:
- Build from MOF definitions of the objects which are compiled into the
repository. See
compile_mof_string()
and Seecompile_mof_file()
. - Build MOF qualifier declarations and classes directly from the DMTF
CIM schema by downloading the schema from the DMTF and selecting all
or part of the schema to compile. This automatically compiles all
qualifiers declarations into the mock repository and allows setting up
a partial class repository (i.e. just selected classes) in a single
method. See section DMTF CIM schema download support and the
compile_dmtf_schema()
method.
- Build from MOF definitions of the objects which are compiled into the
repository. See
It may take a combination of all three of the above methods to build a schema that satisfies a particular requirement including:
- Build the DMTF CIM Classes from the DMTF schema. This is easy to code, and eliminates errors defining components. It also loads all qualifier declarations.
- Build non-DMTF classes (subclasses, etc.) by defining either MOF for the classes and compiling or directly building the pywbem CIM classes.
- Build CIM instances by defining MOF and compiling or directly building the pywbem CIM instances. Often MOF is easier for this because it simplifies the definition of association instances with the instance alias.
- Add the definition of any CIM methods for which the mock server is expected
to respond. add_method_callback. See
add_method_callback()
.
The pywbem MOF compiler provides support for:
- Automatically including all qualifier declaractions if classes are added
with the method
compile_dmtf_schema()
or theDMTFCIMSchema
. - Adding dependent classes from the DMTF schema in the case where they are missing in the compiled mof and the compiler search path includes the MOF directory of the DMTF CIM schema. This include superclasses, reference classes defined in reference properties and parameters, and the class referenced through the EmbeddedInstance qualifier. Thus, the user does not have to track down those dependent classes to be able to create a working mock repository.
Example: Set up qualifier types and classes in DMTF CIM schema¶
This example creates a faked connection and compiles the classes defined in the list ‘classes’ from DMTF schema version 2.49.0 into the repository along with all of the qualifier declarations defined by the DMTF schema and any dependent classes (superclasses, etc.).
import pywbem
import pywbem_mock
conn = pywbem_mock.FakedWBEMConnection(default_namespace='root/interop')
# Leaf classes that are to be compiled along with their dependent classes
leaf_classes = ['CIM_RegisteredProfile',
'CIM_Namespace',
'CIM_ObjectManager',
'CIM_ElementConformsToProfile',
'CIM_ReferencedProfile']
# Compile dmtf schema version 2.49.0, the qualifier declarations and
# the classes in 'classes' and all dependent classes and keep the
# schema in directory my_schema_dir
conn.compile_dmtf_schema((2, 49, 0), "my_schema_dir", classes,
verbose=True)
# Display the resulting repository
conn.display_repository()
Example: Set up qualifier types and classes from MOF¶
This example creates a faked connection and sets up its mock repository with qualifier types and classes that are defined in a MOF string.
import pywbem
import pywbem_mock
tst_namespace = 'root/blah'
conn = pywbem_mock.FakedWBEMConnection()
# Add some qualifier types and classes to the mock repo by compiling MOF
mof = '''
Qualifier Key : boolean = false,
Scope(property, reference),
Flavor(DisableOverride, ToSubclass);
Qualifier Association : boolean,
Scope(class),
Flavor(DisableOverride, ToSubclass);
class TST_Class1 {
[Key]
string InstanceID;
string Prop1;
};
class TST_Class2 {
[Key]
string InstanceID;
string Prop2;
};
[Association]
class TST_Association12 {
[Key]
TST_Class1 REF Ref1;
[Key]
TST_Class2 REF Ref2;
};
'''
conn.compile_mof_string(mof, tst_namespace)
conn.display_repository()
This code displays the mock repository in MOF format after adding these objects:
# ========Mock Repo Display fmt=mof namespaces=all =========
# NAMESPACE root/blah
# Namespace root/blah: contains 2 Qualifier Declarations
Qualifier Association : boolean,
Scope(class),
Flavor(DisableOverride, ToSubclass);
Qualifier Key : boolean = false,
Scope(property, reference),
Flavor(DisableOverride, ToSubclass);
# Namespace root/blah: contains 3 Classes
[Association ( true )]
class TST_Association12 {
[Key ( true )]
TST_Class1 REF Ref1;
[Key ( true )]
TST_Class2 REF Ref2;
};
class TST_Class1 {
[Key ( true )]
string InstanceID;
string Prop1;
};
class TST_Class2 {
[Key ( true )]
string InstanceID;
string Prop2;
};
============End Repository=================
Example: Set up instances from single CIM objects¶
Based on the mock repository content of the previous example, this example adds two class instances and one association instance from their CIM objects.
c1_key = pywbem.CIMProperty('InstanceID', type='string', value='111')
c1_path = pywbem.CIMInstanceName(
'TST_Class1',
keybindings={c1_key.name: c1_key.value},
)
c1 = pywbem.CIMInstance(
'TST_Class1',
properties=[
c1_key,
pywbem.CIMProperty('Prop1', type='string', value='1'),
],
path=c1_path,
)
c2_key = pywbem.CIMProperty('InstanceID', type='string', value='222')
c2_path = pywbem.CIMInstanceName(
'TST_Class2',
keybindings={c2_key.name: c2_key.value},
)
c2 = pywbem.CIMInstance(
'TST_Class2',
properties=[
c2_key,
pywbem.CIMProperty('Prop2', type='string', value='2'),
],
path=c2_path,
)
a12_key1 = pywbem.CIMProperty('Ref1', type='reference', value=c1_path)
a12_key2 = pywbem.CIMProperty('Ref2', type='reference', value=c2_path)
a12_path = pywbem.CIMInstanceName(
'TST_Association12',
keybindings={
a12_key1.name: a12_key1.value,
a12_key2.name: a12_key2.value,
},
)
a12 = pywbem.CIMInstance(
'TST_Association12',
properties=[
a12_key1,
a12_key2,
],
path=a12_path,
)
conn.add_cimobjects([c1, c2, a12], tst_namespace)
conn.display_repository()
This adds the instances to the repository display of the previous example:
# Namespace root/blah: contains 3 Instances
# Path=/root/blah:TST_Class1.InstanceID="111"
instance of TST_Class1 {
InstanceID = "111";
Prop1 = "1";
};
# Path=/root/blah:TST_Class2.InstanceID="222"
instance of TST_Class2 {
InstanceID = "222";
Prop2 = "2";
};
# Path=/root/blah:TST_Association12.Ref1="/:TST_Class1.InstanceID=\"111\"",Ref2="/:TST_Class2.InstanceID=\"222\""
instance of TST_Association12 {
Ref1 = "/:TST_Class1.InstanceID=\"111\"";
Ref2 = "/:TST_Class2.InstanceID=\"222\"";
};
FakedWBEMConnection¶
-
class
pywbem_mock.
FakedWBEMConnection
(default_namespace='root/cimv2', use_pull_operations=False, stats_enabled=False, timeout=None, response_delay=None, repo_lite=False)[source]¶ A subclass of
pywbem.WBEMConnection
that mocks the communication with a WBEM server by utilizing a local in-memory mock repository to generate responses in the same way the WBEM server would.Experimental: New in pywbem 0.12 as experimental.
For a description of the operation methods on this class, see Faked WBEM operations.
Each
FakedWBEMConnection
object has its own mock repository which contains multiple CIM namespaces, and each namespace may contain CIM qualifier types (declarations), CIM classes and CIM instances.This class provides only a subset of the init parameters of
WBEMConnection
because it does not have a connection to a WBEM server. It uses a faked and fixed URL for the WBEM server (http://FakedUrl
) as a means of identifying the connection by users.Logging of the faked operations is supported via the pywbem logging facility and can be controlled in the same way as for
WBEMConnection
. For details, see WBEM operation logging.Parameters: - default_namespace (string) – Default namespace.
This parameter has the same characteristics as the same-named init
parameter of
WBEMConnection
. - use_pull_operations (
bool
) – Flag to control whether pull or traditional operaitons are used in the iter operations. This parameter has the same characteristics as the same-named init parameter ofWBEMConnection
. - timeout (number) – This parameter has the same characteristics as the same-named init
parameter of
WBEMConnection
. - stats_enabled (
bool
) – Flag to enable operation statistics. This parameter has the same characteristics as the same-named init parameter ofWBEMConnection
. - response_delay (number) –
Artifically created delay for each operation, in seconds. This must be a positive number. Delays less than a second or other fractional delays may be achieved with float numbers. None disables the delay.
Note that the
response_delay
property can be used to set this delay subsequent to object creation. - repo_lite (
bool
) – Flag to set the operation mode of the mock repository. If True, lite mode is set. If False, full mode is set.
Methods
AssociatorNames
Retrieve the instance paths of the instances associated to a source instance, or the class paths of the classes associated to a source class. Associators
Retrieve the instances associated to a source instance, or the classes associated to a source class. CloseEnumeration
Close an open enumeration session, causing an early termination of an incomplete enumeration session. CreateClass
Create a class in a namespace. CreateInstance
Create an instance in a namespace. DeleteClass
Delete a class. DeleteInstance
Delete an instance. DeleteQualifier
Delete a qualifier type (= qualifier declaration). 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. EnumerateInstanceNames
Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace. EnumerateInstances
Enumerate the instances of a class (including instances of its subclasses) in a namespace. EnumerateQualifiers
Enumerate the qualifier types (= qualifier declarations) in a namespace. ExecQuery
Execute a query in a namespace. GetClass
Retrieve a class. GetInstance
Retrieve an instance. GetQualifier
Retrieve a qualifier type (= qualifier declaration). InvokeMethod
Invoke a method on a target instance or on a target class. IterAssociatorInstancePaths
Retrieve the instance paths of the instances associated to a source instance, using the Python generator idiom to return the result. IterAssociatorInstances
Retrieve the instances associated to a source instance, using the Python generator idiom to return the result. IterEnumerateInstancePaths
Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result. IterEnumerateInstances
Enumerate the instances of a class (including instances of its subclasses) in a namespace, using the Python generator idiom to return the result. IterQueryInstances
Execute a query in a namespace, using the Python generator idiom to return the result. IterReferenceInstancePaths
Retrieve the instance paths of the association instances that reference a source instance, using the Python generator idiom to return the result. IterReferenceInstances
Retrieve the association instances that reference a source instance, using the Python generator idiom to return the result. ModifyClass
Modify a class. ModifyInstance
Modify the property values of an instance. OpenAssociatorInstancePaths
Open an enumeration session to retrieve the instance paths of the instances associated to a source instance. OpenAssociatorInstances
Open an enumeration session to retrieve the instances associated to a source instance. OpenEnumerateInstancePaths
Open an enumeration session to enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace. OpenEnumerateInstances
Open an enumeration session to enumerate the instances of a class (including instances of its subclasses) in a namespace. OpenQueryInstances
Open an enumeration session to execute a query in a namespace and to retrieve the instances representing the query result. OpenReferenceInstancePaths
Open an enumeration session to retrieve the instance paths of the association instances that reference a source instance. OpenReferenceInstances
Open an enumeration session to retrieve the association instances that reference a source instance. PullInstancePaths
Retrieve the next set of instance paths from an open enumeration session. PullInstances
Retrieve the next set of instances (without instance paths) from an open enumeration session. PullInstancesWithPath
Retrieve the next set of instances (with instance paths) from an open enumeration session. ReferenceNames
Retrieve the instance paths of the association instances that reference a source instance, or the class paths of the association classes that reference a source class. References
Retrieve the association instances that reference a source instance, or the association classes that reference a source class. SetQualifier
Create or modify a qualifier type (= qualifier declaration) in a namespace. add_cimobjects
Add CIM classes, instances and/or CIM qualifier types (declarations) to the specified CIM namespace of the mock repository. add_method_callback
Register a callback function for a CIM method that will be called when the CIM method is invoked via InvokeMethod. add_namespace
Add a CIM namespace to the mock repository. add_operation_recorder
Experimental: Add an operation recorder to this connection. compile_dmtf_schema
Compile the classes defined by class_names and their dependent classes from the DMTF CIM schema version defined by schema_version and keep the downloaded DMTF CIM schema in the directory defined by schema_dir. compile_mof_file
Compile the MOF definitions in the specified file (and its included files) and add the resulting CIM objects to the specified CIM namespace of the mock repository. compile_mof_string
Compile the MOF definitions in the specified string and add the resulting CIM objects to the specified CIM namespace of the mock repository. display_repository
Display the namespaces and objects in the mock repository in one of multiple formats to a destination. imethodcall
Deprecated: Low-level method used by the operation-specific methods of this class. methodcall
Deprecated: Low-level method used by the InvokeMethod()
method of this class.operation_recorder_reset
Experimental: Low-level method used by the operation-specific methods of this class. operation_recorder_stage_pywbem_args
Experimental: Low-level method used by the operation-specific methods of this class. operation_recorder_stage_result
Experimental: Low-level method used by the operation-specific methods of this class. Attributes
ca_certs
Location of CA certificates (trusted certificates) for verifying the X.509 server certificate returned by the WBEM server. conn_id
Connection ID (a unique ID) of this connection. creds
Credentials for HTTP authentication with the WBEM server. debug
Boolean indicating that debug is enabled for this connection. default_namespace
Name of the CIM namespace to be used by default (if no namespace is specified for an operation). host
The {host}[:{port}]
component of the WBEM server’s URL, as specified in theurl
attribute.last_operation_time
Elapsed time of the last operation that was executed via this connection in seconds or None. last_raw_reply
CIM-XML data of the last response received from the WBEM server on this connection, formatted as it was received (=raw). last_raw_request
CIM-XML data of the last request sent to the WBEM server on this connection, formatted as it was sent (=raw). last_reply
CIM-XML data of the last response received from the WBEM server on this connection, formatted as prettified XML. last_reply_len
The size of the HTTP body in the CIM-XML response of the last operation, in Bytes. last_request
CIM-XML data of the last request sent to the WBEM server on this connection, formatted as prettified XML. last_request_len
The size of the HTTP body in the CIM-XML request of the last operation, in Bytes. last_server_response_time
Server-measured response time of the last request, or None. no_verification
Boolean indicating that verifications are disabled for this connection. operation_recorder
Deprecated: The operation recorder that was last added to the connection, or None if the connection does not currently have any recorders. operation_recorder_enabled
Experimental: Enablement status for all operation recorders of the connection. operation_recorders
Experimental: The operation recorders of this connection. repo_lite
Boolean indicating whether the connection was established in the lite mode. response_delay
Artifically created delay for each operation, in seconds. statistics
Statistics for this connection. stats_enabled
Statistics enablement status for this connection. timeout
Timeout in seconds, for requests sent to the server. url
URL of the WBEM server. use_pull_operations
Boolean indicating that the client should attempt the use of pull operations in any Iter…() methods. verify_callback
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. x509
X.509 client certificate and key file to be presented to the WBEM server during the TLS/SSL handshake. Details
-
repo_lite
¶ Boolean indicating whether the connection was established in the lite mode. (True) if the lite mode is set
-
response_delay
¶ Artifically created delay for each operation, in seconds. If None, there is no delay.
This attribute is settable. For details, see the description of the same-named init parameter of
this class
.Type: number
-
add_namespace
(namespace)[source]¶ Add a CIM namespace to the mock repository.
The namespace must not yet exist in the mock repository.
Note that the default connection namespace is automatically added to the mock repository upon creation of this object.
Parameters: namespace (string) – The name of the CIM namespace in the mock repository. Must not be None. Any leading and trailing slash characters are split off from the provided string.
Raises: ValueError
– Namespace argument must not be NoneCIMError
– CIM_ERR_ALREADY_EXISTS if the namespace already exists in the mock repository.
-
compile_mof_file
(mof_file, namespace=None, search_paths=None, verbose=None)[source]¶ Compile the MOF definitions in the specified file (and its included files) and add the resulting CIM objects to the specified CIM namespace of the mock repository.
If the namespace does not exist,
CIMError
with status CIM_ERR_INVALID_NAMESPACE is raised.This method supports all MOF pragmas, and specifically the include pragma.
If a CIM class or CIM qualifier type to be added already exists in the target namespace with the same name (comparing case insensitively), this method raises
CIMError
.If a CIM instance to be added already exists in the target namespace with the same keybinding values, this method raises
CIMError
.In all cases where this method raises an exception, the mock repository remains unchanged.
Parameters: - mof_file (string) – Path name of the file containing the MOF definitions to be compiled.
- namespace (string) – The name of the target CIM namespace in the mock repository. This namespace is also used for lookup of any existing or dependent CIM objects. If None, the default namespace of the connection is used.
- search_paths (iterable of string) – An iterable of directory path names where MOF dependent files will
be looked up.
See the description of the search_path init parameter of the
MOFCompiler
class for more information on MOF dependent files. - verbose (
bool
) – Controls whether to issue more detailed compiler messages.
Raises: IOError
– MOF file not found.MOFParseError
– Compile error in the MOF.CIMError
– CIM_ERR_INVALID_NAMESPACE: Namespace does not exist.CIMError
– Failure related to the CIM objects in the mock repository.
-
compile_mof_string
(mof_str, namespace=None, search_paths=None, verbose=None)[source]¶ Compile the MOF definitions in the specified string and add the resulting CIM objects to the specified CIM namespace of the mock repository.
If the namespace does not exist,
CIMError
with status CIM_ERR_INVALID_NAMESPACE is raised.This method supports all MOF pragmas, and specifically the include pragma.
If a CIM class or CIM qualifier type to be added already exists in the target namespace with the same name (comparing case insensitively), this method raises
CIMError
.If a CIM instance to be added already exists in the target namespace with the same keybinding values, this method raises
CIMError
.In all cases where this method raises an exception, the mock repository remains unchanged.
Parameters: - mof_str (string) – A string with the MOF definitions to be compiled.
- namespace (string) – The name of the target CIM namespace in the mock repository. This namespace is also used for lookup of any existing or dependent CIM objects. If None, the default namespace of the connection is used.
- search_paths (iterable of string) – An iterable of directory path names where MOF dependent files will
be looked up.
See the description of the search_path init parameter of the
MOFCompiler
class for more information on MOF dependent files. - verbose (
bool
) – Controls whether to issue more detailed compiler messages.
Raises: IOError
– MOF file not found.MOFParseError
– Compile error in the MOF.CIMError
– CIM_ERR_INVALID_NAMESPACE: Namespace does not exist.CIMError
– Failure related to the CIM objects in the mock repository.
-
compile_dmtf_schema
(schema_version, schema_root_dir, class_names, use_experimental=False, namespace=None, verbose=False)[source]¶ Compile the classes defined by class_names and their dependent classes from the DMTF CIM schema version defined by schema_version and keep the downloaded DMTF CIM schema in the directory defined by schema_dir.
This method uses the
DMTFCIMSchema
class to download the DMTF CIM schema defined by schema_version from the DMTF, into the schema_root_dir directory, extract the MOF files, create a MOF file with the #include pragma statements for the files in class_names and attempt to compile this set of files.It automatically compiles all of the DMTF qualifier declarations that are in the files qualifiers.mof and qualifiers_optional.mof.
The result of the compilation is added to the specified CIM namespace of the mock repository.
If the namespace does not exist,
CIMError
with status CIM_ERR_INVALID_NAMESPACE is raised.Parameters: - schema_version (tuple of 3 integers (m, n, u) –
Represents the DMTF CIM schema version where:
- m is the DMTF CIM schema major version
- n is the DMTF CIM schema minor version
- u is the DMTF CIM schema update version
This must represent a DMTF CIM schema that is available from the DMTF web site.
- schema_root_dir (string) –
Directory into which the DMTF CIM schema is installed or will be installed. A single schema_dir can be used for multiple schema versions because subdirectories are uniquely defined by schema version and schema_type (i.e. Final or Experimental).
Multiple DMTF CIM schemas may be maintained in the same schema_root_dir simultaneously because the MOF for each schema is extracted into a subdirectory identified by the schema version information.
- class_names (list of string or string) –
List of class names from the DMTF CIM Schema to be included in the repository.
A single class may be defined as a string not in a list.
These must be classes in the defined DMTF CIM schema and can be a list of just the leaf classes required The MOF compiler will search the DMTF CIM schema MOF classes for superclasses, classes defined in reference properties, and classes defined in EmbeddedInstance qualifiers and compile them also.
- use_experimental (
bool
) –If True the expermental version of the DMTF CIM Schema is installed or to be installed.
If False (default) the final version of the DMTF CIM Schema is installed or to be installed.
- namespace (string) – The name of the target CIM namespace in the mock repository. This namespace is also used for lookup of any existing or dependent CIM objects. If None, the default namespace of the connection is used.
- verbose (
bool
) – If True, progress messages are output to stdout
Raises: ValueError
– The schema cannot be retrieved from the DMTF web site, the schema_version is invalid, or a class name cannot be found in the defined DMTF CIM schema.TypeError
– The ‘schema_version’ is not a valid tuple with 3 integer componentsMOFParseError
– Compile error in the MOF.CIMError
– CIM_ERR_INVALID_NAMESPACE: Namespace does not exist.CIMError
– Failure related to the CIM objects in the mock repository.
- schema_version (tuple of 3 integers (m, n, u) –
-
add_cimobjects
(objects, namespace=None)[source]¶ Add CIM classes, instances and/or CIM qualifier types (declarations) to the specified CIM namespace of the mock repository.
This method adds a copy of the objects presented so that the user may modify the objects without impacting the repository.
If the namespace does not exist,
CIMError
with status CIM_ERR_INVALID_NAMESPACE is raised.The method imposes very few limits on the objects added. It does require that the superclass exist for any class added and that instances added include a path component. If the qualifier flavor attributes are not set, it sets them to those defined in the Qualifier Declarations if those exist.
If a CIM class or CIM qualifier type to be added already exists in the target namespace with the same name (comparing case insensitively), this method fails, and the mock repository remains unchanged.
If a CIM instance to be added already exists in the target namespace with the same keybinding values, this method fails, and the mock repository remains unchanged.
Parameters: - objects (
CIMClass
orCIMInstance
orCIMQualifierDeclaration
, or list of them) – CIM object or objects to be added to the mock repository. The list may contain different kinds of CIM objects. - namespace (string) – The name of the target CIM namespace in the mock repository. This namespace is also used for lookup of any existing or dependent CIM objects. If None, the default namespace of the connection is used.
Raises: ValueError
– Invalid input CIM object in objects parameter.TypeError
– Invalid type in objects parameter.CIMError
– CIM_ERR_INVALID_NAMESPACE: Namespace does not exist.CIMError
– Failure related to the CIM objects in the mock repository.
- objects (
-
add_method_callback
(classname, methodname, method_callback, namespace=None)[source]¶ Register a callback function for a CIM method that will be called when the CIM method is invoked via InvokeMethod.
If the namespace does not exist,
CIMError
with status CIM_ERR_INVALID_NAMESPACE is raised.Parameters: - classname (string) –
The CIM class name for which the callback function is registered.
The faked InvokeMethod implementation uses this information to look up the callback function from its parameters.
For method invocations on a target instance, this must be the class name of the creation class of the target instance.
For method invocations on a target class, this must be the class name of the target class.
- methodname (string) –
The CIM method name for which the callback function is registered.
The faked InvokeMethod implementation uses this information to look up the callback function from its parameters.
- method_callback (
method_callback_interface()
) – The callback function. - namespace (string) –
The CIM namespace for which the callback function is registered.
If None, the callback function is registered for the default namespace of the connection.
The faked InvokeMethod implementation uses this information to look up the callback function from its parameters.
Raises: ValueError
– Duplicate method specification.CIMError
– CIM_ERR_INVALID_NAMESPACE: Namespace does not exist.
- classname (string) –
-
display_repository
(namespaces=None, dest=None, summary=False, output_format='mof')[source]¶ Display the namespaces and objects in the mock repository in one of multiple formats to a destination.
Parameters: - namespaces (string or list of string) – Limits display output to the specified CIM namespace or namespaces. If None, all namespaces of the mock repository are displayed.
- dest (string) – File path of the output file. If None, the output is written to stdout.
- summary (
bool
) – Flag for summary mode. If True, only a summary count of CIM objects in the specified namespaces of the mock repository is produced. If False, both the summary count and the details of the CIM objects are produced. - output_format (string) – Output format, one of: ‘mof’, ‘xml’, or ‘repr’.
- default_namespace (string) – Default namespace.
This parameter has the same characteristics as the same-named init
parameter of
DMTF CIM schema download support¶
A DMTF CIM schema is the collection of CIM qualifier declarations and CIM classes managed by the DMTF and released as a single tested, coherent package with a defined major, minor, update version number. The MOF representation of a DMTF schema release is packaged as a single zip file and is available on the DMTF web site ( https://www.dmtf.org/standards/cim ).
Because the DMTF CIM schemas are the source of most of the classes that a WBEM
server normally implements it was important to create a simple mechanism
to include the DMTF CIM classes and qualifier declarations in the
FakedWBEMConnection
mock repository.
The DMTFCIMSchema
class downloads the DMTF CIM schema
zip file defined by version from the DMTF web site into a defined directory,
unzips the MOF files into a subdirectory and makes this subdirectory
available as a property of the DMTFCIMSchema
object.
The implementation of this class depends on all of the qualiifiers and classes in the CIM schema having unique class names; this is always true for DMTF CIM schema releases to assure that they can be installed in the same namespace in a WBEM server repository.
Once a DMTF CIM schema is extracted into the individual MOF files it consumes
considerable space since it expands to almost 3000 files. Therefore it is
logical to remove all of the individual MOF files when not being used and also
if the schema information is to be committed to be used in testing in an
environment like github. Therefore, a method
clean()
removes all of the MOF files from
local storage. They are restored the next time the
DMTFCIMSchema
object for the same version is constructed.
The DMTF maintains two versions of each released schema:
- Final - This schema does not contain any of the schema classes that are marked experimental. It is considered the stable release.
- Experimental - Contains the classes in the final schema plus other classes that are considered experimental. It is considered less stable and the experimental classes with the Experimental qualifier are subject to incompatible changes .
DMTFCIMSchema
will install either the final or
experimental schema depending on the value of the use_experimental
parameter.
Because it is usually necessary to compile only a subset of the DMTF CIM
classes into a mock repository for any test, the
DMTFCIMSchema
class provides a
build_schema_mof()
method to create a
MOF include file that includes only a subset of the classes in the downloaded
DMTF CIM Schema. The task of listing classes to be compiled is futher
simplified because the pywbem MOF compiler searches the DMTF schema for
prerequisite classes (superclasses, reference classes, and EmbeddedInstance
classes) so that generally only the leaf CIM classes required for the
repository need to be in the class list. This speeds up the process of
compiling DMTF CIM classes for any test significantly.
-
class
pywbem_mock.
DMTFCIMSchema
(schema_version, schema_root_dir, use_experimental=False, verbose=False)[source]¶ DMTFCIMSchema
represents a DMTF CIM Schema downloaded from the DMTF web site.This class manages the download of the DMTF schema zip file and extraction of MOF files of DMTF CIM schema releases into a directory that can be used by
FakedWBEMConnection
to compile a mock repository with class and qualifier declarations.The init method downloads the schema if the schema_root_dir or the schema zip file do not exist into the directory defined by the schema_root_dir parameter and extracts the MOF files into schema_mof_dir.
If the schema zip file is already downloaded it simply sets the
DMTFCIMSchema
property values.If the schema zip file was previously downloaded but schema_mof_dir does not exist the directory is created and the MOF files are extracted into this directory.
Parameters: - schema_version (tuple of 3 integers (m, n, u) –
Represents the DMTF CIM schema version m.n.u where:
- m is the DMTF CIM schema major version
- n is the DMTF CIM schema minor version
- u is the DMTF CIM schema update version
This must represent a DMTF CIM schema that is available from the DMTF web site.
- schema_root_dir (string) –
Path name of the schema root directory into which the DMTF CIM schema zip file is downloaded and in which a subdirectory for the extracted MOF files is created
Multiple DMTF CIM schemas may be maintained in the same schema_root_dir simultaneously because the MOF for each schema is extracted into a subdirectory identified by the schema version information.
- use_experimental (
bool
) –If True, the experimental version of the defined DMTF schema is installed.
If False, (default) the final version of the defined DMTF schema is installed.
- verbose (
bool
) – If True, progress messages are output to stdout as the schema is downloaded and expanded. Default is False.
Raises: ValueError
– if the schema cannot be retrieved from the DMTF web site.TypeError
– if the schema_version is not a valid tuple with 3 integer components
Methods
build_schema_mof
Build a string that includes the #include pragma
statements for the DMTF schema CIM classes defined in schema_classes using the DMTF CIM schema defined by this object.clean
Remove all of the MOF files and the schema_mof_dir for the defined schema. remove
The schema_mof_dir directory is removed if it esists and the schema_zip_file is removed if it exists. Attributes
schema_mof_dir
Path name of the directory in which the DMTF CIM Schema MOF files are extracted from the downloaded zip file. schema_mof_file
Path name of the DMTF CIM schema MOF top level file which used to compile the complete CIM schema. schema_root_dir
Path name of the directory in which the DMTF CIM Schema zip file is downloaded. schema_version
of 3 integers with major version, minor version, and update version of the DMTF Schema installed. schema_version_str
with the DMTF CIM schema version in the form <major version>.<minor version>.<update version>. schema_zip_file
Path name of the DMTF CIM schema zip file downloaded from the DMTF web site. schema_zip_url
Url for the DMTF CIM Schema version that is downloaded. Details
-
schema_version
¶ of 3 integers with major version, minor version, and update version of the DMTF Schema installed. Ex (2, 49, 0) defines DMTF schema version 2.49.0.
Type: tuple()
-
schema_version_str
¶ with the DMTF CIM schema version in the form <major version>.<minor version>.<update version>.
Type: string
-
schema_root_dir
¶ Path name of the directory in which the DMTF CIM Schema zip file is downloaded. the MOF files are extracted into a subdirectory, schema_mof_dir.
Type: string
-
schema_mof_dir
¶ Path name of the directory in which the DMTF CIM Schema MOF files are extracted from the downloaded zip file. This property is useful since it can be used as the MOF compiler search path for compiling classes in the DMTF CIM schema.
Type: string
-
schema_mof_file
¶ Path name of the DMTF CIM schema MOF top level file which used to compile the complete CIM schema. This file contains the #pragama include statements for all of the classes in the schema and the qualifier declaration #pragma include statements to compile qualifiers.mof and qualifiers_optional.mof.
This filename is of the general form:
<schema_mof_dir>/cim_schema_<schema_version_str>.mof ex: schemas/dmtf/moffinal2490/cim_schema_2.49.0.mof
Type: string
-
schema_zip_file
¶ Path name of the DMTF CIM schema zip file downloaded from the DMTF web site.
Type: string
-
__str__
()[source]¶ Return a short string representation of the
DMTFCIMSchema
object for human consumption. This displays the major properties of the object.
-
__repr__
()[source]¶ Return a string representation of the
DMTFCIMSchema
object that is suitable for debugging.
-
build_schema_mof
(schema_classes)[source]¶ Build a string that includes the
#include pragma
statements for the DMTF schema CIM classes defined in schema_classes using the DMTF CIM schema defined by this object.The class names in this list can be just leaf classes. The pywbem MOF compiler will search for dependent classes.
It builds a compilable MOF string in the form:
#pragma locale ("en_US") #pragma include ("System/CIM_ComputerSystem.mof")
with a
#pragma include
for each classname in the schema_classes listParameters: schema_classes (list of string or string) –
These must be class names of classes in the DMTF CIM schema represented by this
DMTFCIMSchema
object. This parameter can be a string if there is only a single class name to be included.If the returned string is compiled, the MOF compiler will search the directory defined by schema_mof_dir for dependent classes.
Returns: Valid MOF containing pragma statements for all of the classes in schema_classes.
Return type: Raises: ValueError
– If any of the classnames in schema_classes are not in- the DMTF CIM schema installed
-
clean
()[source]¶ Remove all of the MOF files and the schema_mof_dir for the defined schema. This is useful because while the downloaded schema is a single compressed zip file, it creates several thousand MOF files that take up considerable space.
The next time the
DMTFCIMSchema
object for this schema_version and schema_root_dir is created, the MOF file are extracted again.
- schema_version (tuple of 3 integers (m, n, u) –
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.
Setting up the development environment¶
It is recommended to use Linux as the development environment for pywbem. OS-X should work as well, but Windows requires a number of manual setup steps.
Clone the Git repo of this project and switch to its working directory:
$ git clone git@github.com:pywbem/pywbem.git $ cd pywbem
It is recommended that you set up a virtual Python environment. Have the virtual Python environment active for all remaining steps.
Install pywbem and its prerequisites for installing and running it as described in Installation. This will install Python packages into the active Python environment, and OS-level packages.
On Windows, perform the setup steps described in Manual setup on Windows. On Linux and OS-X, the corresponding setup is performed automatically as part of the next step.
Install the prerequsites for pywbem development. This will install Python packages into the active Python environment, and OS-level packages:
$ make develop
This project uses Make to do things in the currently active Python environment. The command:
$ make
displays a list of valid Make targets and a short description of what each target does.
Manual setup on Windows¶
For development of pywbem, it is recommended to use one of the Unix-like environments on Windows (such as CygWin, MinGW, Babun, or Gow). The pywbem tests that run on the Appveyor CI use CygWin.
Note that Unix-like environments on Windows bring their own Python, so double check that the active Python environment is the one you want to install to.
The development environment needs the xmllint
utility and the lxml
Python package.
The lxml
Python package for Windows meanwhile comes as a binary wheel
archive that includes all of its dependencies, so it has no additional
dependencies you would need to take care about.
The xmllint
utility is part of CygWin and likely also part of the other
Unix-like environments.
Prerequisite operating system packages for development¶
The following table lists the prerequisite operating system packages along with their version requirements for development of pywbem, for the supported operating systems and Linux distributions.
The prerequisite operating system packages for installing and running pywbem are also needed for development, and can be found in section Prerequisite operating system packages for install.
This section is just for information. These packages will be installed as part of the steps described in Setting up the development environment.
Op.system / Distribution | Package name | Version requirements | Notes |
---|---|---|---|
Linux RedHat family (RHEL, CentOS, Fedora) | |||
Linux Debian family (Ubuntu, Debian, LinuxMint) | |||
Linux SUSE family (SLES, openSUSE) | |||
OS-X | |||
Windows | xmllint |
Building the documentation¶
The ReadTheDocs (RTD) site is used to publish the documentation for the pywbem package at https://pywbem.readthedocs.io/
This page is automatically updated whenever the Git repo for this package changes the branch from which this documentation is built.
In order to build the documentation locally from the Git work directory, execute:
$ make builddoc
The top-level document to open with a web browser will be
build_doc/html/docs/index.html
.
Testing¶
All of the following make commands run the tests in the currently active Python environment, and need to be invoked in the Git repo work directory.
By default, the tests use the pywbem and pywbem_mock modules from the respective directories in the Git repo work directory. Pywbem 0.14.5 introduced a way to test installed versions of the pywbem package. For details, see Testing installed versions of pywbem.
The tests directory has the following subdirectory structure:
tests
+-- unittest Unit tests
| +-- utils Utility functions used by unit tests
| +-- pywbem Unit tests for the pywbem package
| +-- pywbem_mock Unit tests for the pywbem_mock package
| +-- unittest_utils Unit tests for tests/unittest/utils
| +-- functiontest Unit tests for tests/functiontest
| +-- end2endtest_utils Unit tests for tests/end2endtest/utils
| +-- servers Unit tests for tests/servers
+-- functiontest Function tests
+-- end2endtest End2end tests
| +-- utils Utility functions used by end2end tests
+-- manualtest Manual tests
+-- server_definitions WBEM server definition file used by some tests and module
| for accessing it
+-- profiles Simple definitions of management profiles used by some tests
+-- schema The CIM schema MOF files used by some MOF tests
+-- dtd The CIM DTD file used by some CIM-XML validation tests
There are multiple types of tests in pywbem:
Unit tests and function tests
These tests do not require any WBEM server to be available, and the tests validate their results automatically.
The distinction between unit tests and function tests as used in pywbem is that function tests exercise the entire pywbem client component or entire pywbem scripts, while unit tests exercise single modules.
They are run by executing:
$ make test
Test execution can be modified by a number of environment variables, as documented in the make help (execute make help).
End2end tests
These tests are run against one or more WBEM servers, and the tests validate their results automatically.
They are run by preparing a server definition file:
tests/server_definitions/server_definition_file.yml
from the provided example, and by executing:
$ make end2end
Again, test execution can be modified by a number of environment variables, as documented in the make help (execute make help).
Manual tests
There are several Python scripts and shell scripts that can be run manually. The results need to be validated manually.
These scripts are in the directory:
tests/manualtest/
and are executed by simply invoking them from within the main directory of the repository, e.g.:
tests/manualtest/run_cim_operations.py
Some of the scripts support a –help option that informs about their usage.
The run_cim_operations.py script needs a particular MOF file loaded in the repository of the WBEM server that is used for the test. This can be done using the MOF compiler of pywbem:
$ mof_compiler -s <target_url> tests/unittest/pywbem/test.mof
To run the unit and function tests in all supported Python environments, the Tox tool can be used. It creates the necessary virtual Python environments and executes make test (i.e. the unit and function tests) in each of them.
For running Tox, it does not matter which Python environment is currently active, as long as the Python tox package is installed in it:
$ tox # Run tests on all supported Python versions
$ tox -e py27 # Run tests on Python 2.7
Testing installed versions of pywbem¶
By default, the tests use the pywbem and pywbem_mock modules from the respective directories in the Git repo work directory.
Pywbem 0.14.5 introduced a way to test installed versions of the pywbem package. This is useful for example for testing a version of pywbem that has been packaged as an OS-level package. Typically, such a version would be installed into the system Python.
Some words of caution:
- Testing an installed version of pywbem with test cases from a pywbem repo
of a different version can result in failing test cases for several reasons:
- If a new version of pywbem has added functionality, its test cases are also extended accordingly. Running such newer test cases against an older installed version of pywbem may fail simply because the installed version does not yet have the added functionality.
- Fixes in pywbem or in the test cases may change behavior in a subtle way that causes test cases to fail.
- Unit test cases are particularly vulnerable to version mismatches because they test at the module level, including module interfaces that are internal to pywbem and thus can legally change incompatibly between versions.
- If the version of the installed pywbem is before 0.14.5, some test cases that compile MOF will be skipped to avoid permission denied errors when ply attempts to re-generate its parsing table files in the pywbem installation directory in case of ply version mismatches. Starting with pywbem 0.14.5, it has tolerance against ply version mismatches.
In order to not clutter up the system Python with Python packages needed for running the pywbem tests, the following steps use a virtual Python environment that uses the packages of the system Python. That way, the installed version of pywbem becomes available to the virtual Python environment from the system Python, while any additional packages that are needed but not yet available that way, will be installed into the virtual Python environment.
Follow these steps to run pywbem tests against a version of pywbem that is installed into the system Python:
Verify that the following commands are available when the system Python is active:
$ virtualenv --version # Python virtualenv package $ pip --version
Create and activate a virtual Python environment of the intended Python version, that is based on the system Python:
$ virtualenv --system-site-packages --no-setuptools --no-pip --no-wheel .virtualenv/test $ source .virtualenv/test/bin/activate
The pywbem project is set up so that Git ignores the
.virtualenv
directory, so use that directory name for ease of Git handling.Verify that in that virtual Python environment, pywbem comes from the intended installation:
$ pip show pywbem
Ensure a fresh start of the make process. This should be done whenever switching between the installed version of pywbem and the local directories:
$ make clobber
Some distributions install the ‘wbemcli’ command of pywbem under a different command name than
wbemcli
. Find out what that name is, and if it is different, set theTEST_WBEMCLI_NAME
environment variable to that command name (e.g for a command name ofpywbemcli
):$ export TEST_WBEMCLI_NAME=pywbemcli
Run the pywbem tests with environment variable
TEST_INSTALLED
being set:$ TEST_INSTALLED=1 make test
This will assume that the pywbem package and any prerequisite Python packages and OS-level packages are already installed.
This will also move the current directory (i.e. the repo working directory) to the end of the module search path, so that the installed version of pywbem is used when importing it into the test scripts.
Setting
TEST_INSTALLED=DEBUG
causes some debug messages to be printed that allow verifying from where the pywbem and pywbem_mock modules are loaded.This also works for the pywbem end2end tests:
$ TEST_INSTALLED=1 make end2end
Note that tox does not support creating its virtual Python environments based on the system Python, so at this point, tox cannot be used for this approach.
Updating the DMTF MOF Test Schema¶
Pywbem uses DMTF CIM Schemas in its CI testing. The schema used is stored in
the form received from the DMTF in the directory tests/schema
and is
expanded and compiled as part of the unit tests.
Since the DMTF regularly updates the schema, the pywbem project tries to stay up-to-date with the current schema. At the same time, earlier schemas can be used for testing also by changing the definitions for the dmtf schema to be tested.
The schema used for testing can be modified by modifying the test file:
tests/unittest/utils/dmtf_mof_schema_def.py
Developing PyWBEM Ipython Documentation Notebooks¶
The pywbem developers are using ipython notebooks to demonstrate the use of pywbem. Today we generally have one notebook per operation or group of operations including definition of the operation, references back to the pywbem documentation, and one or more examples (hopefully examples that will actually execute against a wbem server)
These can easily be extended or supplemented using a local ipython or jupyter server by:
1. Install ipython or Jupyter software using pip or pip3. The notebook server may be installed as root or within a python virtual environment. For example:
$ sudo pip install ipython
or
$ sudo pip3 install ipython
or
$ sudo pip install jupyter
The notebook server may be installed as root or within a python virtual environment.
2. Start the local ipython/jupyter notebook server in the notebook directory (pywbem/docs/notebooks) referencing that directory in the command line call:
$ ipython notebook docs/notebooks
or
$ jupyter notebook docs/notebooks
This will start the local ipython/juypter notebook server and on the first page displayed in your web browser all existing pywbem ipython notebooks will be available for editing. New ones can be created using the commands on that ipython server web page.
New and changed notebooks must go through the same contribution process as other components of pywbem to be integrated into the github repository.
Contributing¶
Third party contributions to this project are welcome!
In order to contribute, create a Git pull request, considering this:
- Test is required.
- Each commit should only contain one “logical” change.
- A “logical” change should be put into one commit, and not split over multiple commits.
- Large new features should be split into stages.
- The commit message should not only summarize what you have done, but explain why the change is useful.
- The commit message must follow the format explained below.
What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.
For further discussion of good and bad practices regarding commits, see:
Core Development Team¶
Anyone can contribute to pywbem via pull requests as described in the previous section.
The pywbem project has a core development team that holds regular web conferences and that is using Slack for offline communication, on the Slack workspace: https://pywbem.slack.com.
The web conference and the Slack workspace are by invitation, and if you want to participate in the core team, please open an issue to let us know.
Appendix¶
This section contains information that is referenced from other sections, and that does not really need to be read in sequence.
Special type names¶
This documentation uses a few special terms to refer to Python types:
- string
- a unicode string or a byte string
- unicode string
- a Unicode string type (
unicode
in Python 2, andstr
in Python 3) - byte string
- a byte string type (
str
in Python 2, andbytes
in Python 3). Unless otherwise indicated, byte strings in pywbem are always UTF-8 encoded. - connection id
- a string (string) that uniquely identifies each
pywbem.WBEMConnection
object created. The connection id is immutable and is accessible frompywbem.WBEMConnection.conn_id
. It is included in of each log record created for pywbem log output and may be used to correlate pywbem log records for a single connection. - number
- one of the number types
int
,long
(Python 2 only), orfloat
. - integer
- one of the integer types
int
orlong
(Python 2 only). - callable
- a callable object; for example a function, a class (calling it returns a
new object of the class), or an object with a
__call__()
method. - hashable
- a hashable object. Hashability requires an object not only to be able to
produce a hash value with the
hash()
function, but in addition that objects that are equal (as per the==
operator) produce equal hash values, and that the produced hash value remains unchanged across the lifetime of the object. See term “hashable” in the Python glossary, although the definition there is not very crisp. A more exhaustive discussion of these requirements is in “What happens when you mess with hashing in Python” by Aaron Meurer. - unchanged-hashable
- an object that is hashable with the exception that its hash value may change over the lifetime of the object. Therefore, it is hashable only for periods in which its hash value remains unchanged. CIM objects are examples of unchanged-hashable objects in pywbem.
- DeprecationWarning
- a standard Python warning that indicates a deprecated functionality.
See section Deprecation and compatibility policy and the standard
Python module
warnings
for details. - Element
- class
xml.dom.minidom.Element
. Its methods are described in section Element Objects of modulexml.dom
, with minidom specifics described in section DOM Objects of modulexml.dom.minidom
. - CIM data type
- one of the types listed in CIM data types.
- CIM object
- one of the types listed in CIM objects.
- keybindings input object
a Python object used as input for initializing an ordered list of keybindings in a parent object (i.e. a
CIMInstanceName
object).None will result in an an empty list of keybindings.
Otherwise, the type of the input object must be one of:
- iterable of
CIMProperty
- iterable of tuple(key, value)
OrderedDict
with key and valuedict
with key and value (will not preserve order)
with the following definitions for key and value:
key (string): Keybinding name.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or number or
CIMProperty
): Keybinding value.If specified as CIM data type or number, the provided object will be stored unchanged as the keybinding value.
If specified as a
CIMProperty
object, its name attribute must match the key (case insensitively), and a copy of its value (a CIM data type) will be stored as the keybinding value.None for the keybinding value will be stored unchanged.
The order of keybindings in the parent object is preserved if the input object is an iterable or a
OrderedDict
object, but not when it is adict
object.The resulting set of keybindings in the parent object is independent of the input object (except for unmutable objects), so that subsequent modifications of the input object by the caller do not affect the parent object.
- iterable of
- methods input object
a Python object used as input for initializing an ordered list of methods represented as
CIMMethod
objects in a parent object that is aCIMClass
.None will result in an an empty list of methods.
Otherwise, the type of the input object must be one of:
- iterable of
CIMMethod
- iterable of tuple(key, value)
OrderedDict
with key and valuedict
with key and value (will not preserve order)
with the following definitions for key and value:
key (string): Method name.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (
CIMMethod
): Method declaration.Must not be None.
The name attribute of the
CIMMethod
object must match the key (case insensitively).The provided object is stored in the parent object without making a copy of it.
The order of methods in the parent object is preserved if the input object is an iterable or a
OrderedDict
object, but not when it is adict
object.The resulting set of methods in the parent object is independent of the input collection object, but consists of the same
CIMMethod
objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the providedCIMMethod
objects.- iterable of
- parameters input object
a Python object used as input for initializing an ordered list of parameters represented as
CIMParameter
objects in a parent object that is aCIMMethod
.None will result in an an empty list of parameters.
Otherwise, the type of the input object must be one of:
- iterable of
CIMParameter
- iterable of tuple(key, value)
OrderedDict
with key and valuedict
with key and value (will not preserve order)
with the following definitions for key and value:
key (string): Parameter name.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (
CIMParameter
): Parameter (declaration).Must not be None.
The name attribute of the
CIMParameter
object must match the key (case insensitively).The provided object is stored in the parent object without making a copy of it.
The order of parameters in the parent object is preserved if the input object is an iterable or a
OrderedDict
object, but not when it is adict
object.The resulting set of parameters in the parent object is independent of the input collection object, but consists of the same
CIMParameter
objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the providedCIMParameter
objects.- iterable of
- properties input object
a Python object used as input for initializing an ordered list of properties represented as
CIMProperty
objects, in a parent object.The
CIMProperty
objects represent property values when the parent object is aCIMInstance
, and property declarations when the parent object is aCIMClass
.None will result in an an empty list of properties.
Otherwise, the type of the input object must be one of:
- iterable of
CIMProperty
- iterable of tuple(key, value)
OrderedDict
with key and valuedict
with key and value (will not preserve order)
with the following definitions for key and value:
key (string): Property name.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or
CIMProperty
): Property (value or declaration).Must not be None.
CIMProperty
objects can be used as input for both property values and property declarations. CIM data type objects can only be used for property values.If specified as a CIM data type, a new
CIMProperty
object will be created from the provided value, inferring its CIM data type from the provided value.If specified as a
CIMProperty
object, its name attribute must match the key (case insensitively), and the provided object is stored in the parent object without making a copy of it.
The order of properties in the parent object is preserved if the input object is an iterable or a
OrderedDict
object, but not when it is adict
object.The resulting set of properties in the parent object is independent of the input collection object, but consists of the same
CIMProperty
objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the providedCIMProperty
objects.- iterable of
- qualifiers input object
a Python object used as input for initializing an ordered list of qualifiers represented as
CIMQualifier
objects in a parent object (e.g. in aCIMClass
object).None will result in an an empty list of qualifiers.
Otherwise, the type of the input object must be one of:
- iterable of
CIMQualifier
- iterable of tuple(key, value)
OrderedDict
with key and valuedict
with key and value (will not preserve order)
with the following definitions for key and value:
key (string): Qualifier name.
Must not be None.
The lexical case of the string is preserved. Object comparison and hash value calculation are performed case-insensitively.
value (CIM data type or
CIMQualifier
): Qualifier (value).Must not be None.
If specified as a CIM data type, a new
CIMQualifier
object will be created from the provided value, inferring its CIM data type from the provided value.If specified as a
CIMQualifier
object, its name attribute must match the key (case insensitively), and the provided object is stored in the parent object without making a copy of it.
The order of qualifiers in the parent object is preserved if the input object is an iterable or a
OrderedDict
object, but not when it is adict
object.The resulting set of qualifiers in the parent object is independent of the input collection object, but consists of the same
CIMQualifier
objects that were provided in the input collection. Therefore, a caller must be careful to not accidentally modify the providedCIMQualifier
objects.- iterable of
Profile advertisement methodologies¶
This section briefly explains the profile advertisement methodologies defined by DMTF. A full description can be found in DSP1033.
These methodologies describe how a client can discover the central instances of a management profile. Discovering the central instances through a management profile is the recommended approach for clients, over simply enumerating a CIM class of choice. The reason is that this approach enables clients to work seamlessly with different server implementations, even when they have implemented a different set of management profiles.
DMTF defines three profile advertisement methodologies in DSP1033:
- GetCentralInstances methodology (new in DSP1033 1.1)
- Central class methodology
- Scoping class methodology
At this point, the GetCentralInstances methodology has not widely been implemented, but pywbem supports it nevertheless.
All three profile advertisement methodologies start from the CIM_RegisteredProfile instance that identifies the management profile, by means of registered organisation, registered name, and registered version.
It is important to understand that the CIM_RegisteredProfile instance not only identifies the management profile, but represents a particular use of the management profile within its scoping profiles. For an autonomous profile, there are no scoping profiles, so in that case, there is only one use of the autonomous profile in a server. However, component profiles do have scoping profiles, and it is well possible that a component profile is used multiple times in a server, in different scoping contexts. If that is the case, and if discovery of central instances using any of the profile advertisement methodologies is supposed to work, then each such use of the profile needs to have its own separate CIM_RegisteredProfile instance, because each such use of the profile will also have its own separate set of central instances.
Unfortunately, neither the DMTF standards nor the SMI-S standards are clear about that requirement, and so there are plenty of implementations that share a single CIM_RegisteredProfile instance identifying a particular component profile, for multiple distinct uses of the profile by its scoping profiles. In such a case, the profile advertisement methodologies will not be able to distinguish the distinct sets of central instances alone, and other means need to be used to distinguish them.
It is also important to understand that the choice which profile advertisement methodology to implement, is done by the WBEM server side. Therefore, a WBEM client such as pywbem needs to support all methodologies and needs to try them one by one until one succeeds. Pywbem tries the three methodologies in the order listed above.
In the GetCentralInstances methodology, the CIM_RegisteredProfile instance has a CIM method named GetCentralInstances that returns the instance paths of the central instances of the use of the profile.
In the central class methodology, the CIM_RegisteredProfile instance is associated directly with the set of central instances of the use of the profile, via a CIM_ElementConformsToProfile association.
In the scoping class methodology, the CIM_RegisteredProfile instance is not associated directly with the set of central instances of the use of the profile, but delegates that to its scoping profile. The client navigates up to the CIM_RegisteredProfile instance representing the (use of the) scoping profile, looks up its central instances, and from each of those, navigates down along the reversed scoping path to the central instances of the profile in question. The scoping path of a component profile describes the traversal across associations and ordinary classes from the central class to the scoping class of the profile. This profile advertisement methodology is obviously the most complex one of the three.
Pywbem encapsulates the complexity and choice of these methodologies into
a single invocation of an easy-to use method
get_central_instances()
.
Profile implementations in a WBEM server are not entirely free when making a choice of which methodology to implement:
Autonomous profiles in a WBEM server must implement the central class methodology, and may in addition implement the new GetCentralInstances methodology.
Note that the scoping class methodology falls together with the central class methodology for autonomous profiles, because their scoping class is also their central class.
Component profiles in a WBEM server may implement the central class methodology and the new GetCentralInstances methodology, and must support the scoping class methodology.
Note that implementing the scoping class methodology in a WBEM server requires implementing the classes and associations of the scoping path, which are usually mandatory anyway. So while the scoping class methodology is more complex to use for clients than the central class methodology, it is easier to implement for servers.
Use of the scoping class methodology by a client requires knowing the central class, scoping class and scoping path defined by the component profile.
DSP1001 requires that conformant autonomous profiles specify a central class, and that conformant component profiles specify a central class, scoping class and a scoping path.
Older DMTF component profiles and older SNIA subprofiles do not always specify scoping class and scoping path. In such cases, the scoping class and scoping path can often be determined from the class diagram in the specification for the profile. Many times, CIM_System or CIM_ComputerSystem is the scoping class.
Troubleshooting¶
Here are some trouble shooting hints for the installation of pywbem.
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. For more details, see Prerequisite operating system packages for development.
Installation fails with “invalid command ‘bdist_wheel’”¶
The installation of M2Crypto and probably other Python packages requires the Python “wheel” package. If that package is not installed in the current Python environment, the installation will fail with the following (or similar) symptom:
Creating library build\temp.win-amd64-2.7\Release\SWIG_m2crypto.lib and object build\temp.win- amd64-2.7\Release\SWIG_m2crypto.exp
python setup.py bdist_wheel
usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
or: setup.py --help [cmd1 cmd2 ...]
or: setup.py --help-commands
or: setup.py cmd --help
error: invalid command 'bdist_wheel'
To fix this, install the Python “wheel” package:
pip install wheel
Installation on Windows fails downloading or executing Win64OpenSSL-1_1_0j.exe¶
The installation of M2Crypto on Windows requires an OpenSSL package, which is provided by Win32OpenSSL from https://slproweb.com/. The maintainer of that project has decided to remove the previous version of Win32OpenSSL whenever he releases a new version. Whenever such a release happens, this breaks the installation of pywbem on Windows (and of any other project that downloads Win32OpenSSL automatically).
The symptom is that the installation of pywbem fails inside of pywbem_os_setup.bat with an error message like this:
pywbem_os_setup.bat: Error: The Win64OpenSSL-1_1_0j.exe file does not exist on https://slproweb.com.
In the past, this issue has surfaced with a different symptom:
Win64OpenSSL-1_1_0j.exe /silent /verysilent /suppressmsgboxes /dir="C:\OpenSSL-1-1-0j-Win64"
The system cannot execute the specified program.
pywbem_os_setup.bat: Error: Command returned rc=1
This issue will be fixed by the pywbem project by upgrading the version number of Win32OpenSSL relatively shortly (because we have regular test runs on the Appveyor CI), but in case you have run into this issue, here is how to get over it by yourself:
Edit the file pywbem_os_setup.bat, and change the following versions to the latest released version of Win32OpenSSL on https://slproweb.com/products/Win32OpenSSL.html:
set _WIN32OPENSSL_VERSION_UNDERSCORED=1_1_0j
set _WIN32OPENSSL_VERSION_DASHED=1-1-0j
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.
References¶
- DSP0004
- DMTF DSP0004, CIM Infrastructure, Version 2.8
- DSP0200
- DMTF DSP0200, CIM Operations over HTTP, Version 1.4
- DSP0201
- DMTF DSP0201, Representation of CIM in XML, Version 2.4
- DSP0207
- DMTF DSP0207, WBEM URI Mapping, Version 1.0
- DSP0212
- DMTF DSP0212, Filter Query Language, Version 1.0.1
- DSP1001
- DMTF DSP1001, Management Profile Specification Usage Guide, Version 1.1
- DSP1033
- DMTF DSP1033, Profile Registration Profile, Version 1.1
- DSP1054
- DMTF DSP1054, Indications Profile, Version 1.2
- DSP1092
- DMTF DSP1092, WBEM Server Profile, Version 1.0
- X.509
- ITU-T X.509, Information technology - Open Systems Interconnection - The Directory: Public-key and attribute certificate frameworks
- RFC2616
- IETF RFC2616, Hypertext Transfer Protocol – HTTP/1.1, June 1999
- RFC2617
- IETF RFC2617, HTTP Authentication: Basic and Digest Access Authentication, June 1999
- RFC3986
- IETF RFC3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005
- RFC6874
- IETF RFC6874, Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers, February 2013
- WBEM Standards
- DMTF WBEM Standards
- Python Glossary
Change log¶
pywbem 0.14.6¶
Released: 2019-10-10
Bug fixes:
- Fixed case sensitive class name check in mock support of ModifyInstance (See issue #1859)
- Test: Fixed args of WBEMOperation methods in mock unit tests & function tests.
Cleanup:
- Test: Enabled Python warning suppression for PendingDeprecationWarning and ResourceWarning (py3 only), and fixed incorrect make variable for that. (See issue #1720)
- Test: Removed pinning of testfixtures to <6.0.0 for Python 2.7/3.x due to deprecation issue announced for Python 3.8, and increased its minimum version from 4.3.3 to 6.9.0.
- Test: Increased minimum version of pytest from 3.3.0 to 4.3.1 because it fixed an issue that surfaced with pywbem minimum package levels on Python 3.7.
- Increased minimum version of PyYAML from 3.13 to 5.1 due to deprecation issue announced for Python 3.8.
pywbem 0.14.5¶
Released: 2019-09-29
Bug fixes:
- Added test to tests/manual/cim_operations.py specifically to test the iter and pull operations for the IncludeQualifier and LocalOnly parameters based on issue #1780.
- Dev/Test: Pinned lxml to <4.4.0 because that version removed Python 3.4 support.
- Dev/Test: Pinned pytest to <5.0.0 for Python < 3.5 because that version requires Python >= 3.5.
- Test: Fixed errors on Python 2.6 about unnamed format replacements.
- Fixed incorrect format specifiers in exceptions raised in pywbem_mock. (See issue #1817)
- Fixed missing support for the ANY scope in pywbem_mock. (See issue #1820)
- Increased version of WinOpenSSL used on Windows from 1.1.0k to 1.1.0L.
- Fixed that the OpenEnumerateInstances() method of WBEMConnections incorrectly supported a LocalOnly parameter, that was never supported as per DSP0200. Specifying that parameter as True or False on this method caused properly implemented WBEM servers to reject the operation. That parameter now still exist on this operation but is ignored and is not passed on to WBEM servers. The corresponding Iter…() method now also ignores that parameter if the pull operations are used; it is still passed on if the traditional operations are used. (See issue #1780)
- Fixed the issue that EnumerateInstances did not return instances without properties unless DeepInheritance was set (see issue #1802).
- Fixed bad formatting on –mock-server option in wbemcli.py.
- Fixed the issue with ‘dnf makecache fast’ during pywbem_os_setup.sh on Fedora (See issue #1844)
Enhancements:
- Improved handling of missing WinOpenSSL on Windows by recommending manual download of next version.
- Test: Added support for running the pywbem tests against an installed version of pywbem, ignoring the version of pywbem that exists in the respective directories of the repo work directory. This is useful for testing a version of pywbem that has been installed as an OS-level package. (See issue #1803)
- Docs: Improved the section about installing to a native Windows environment (See issue #1804)
- Improved error messages and error handling in wbemcli and in the pywbem mock support.
pywbem 0.14.4¶
Released: 2019-07-20
Bug fixes:
- Test: For Python 2.6 on Travis, pinned the distro version to Ubuntu trusty (14.04) because the default distro version on Travis changed to xenial (16.04) which no longer has Python 2.6.
- Add Jupyter tutorial for pywbem_mock to table of notebooks in documentation.
- Fix issue with Python 3 and WBEMconnection certificate handling. pywbem was getting AttributeError: ‘SSLContext’ object has no attribute ‘load_cert’ because incorrect method called. (See issue # 1769)
- Fixed that the WBEMConnection.Open…() operations incorrectly supported an IncludeQualifiers parameter, that was never supported as per DSP0200. Specifying that parameter as True on these operations caused properly implemented WBEM servers to reject the operation. The parameter is now ignored on these operations. Since this parameter was documented as deprecated in DSP0200 and documented that users could not rely on qualifiers to be returned, this fix should not break user code. The WBEMConnection.Iter…() operations now also ignore that parameter if the pull operations are used, and the documentation has been updated accordingly. (See issue #1780)
Enhancements:
- Docs: Clarified how the pywbem_os_setup.sh/bat scripts can be downloaded using a predictable URL, for automated downloads.
Cleanup:
- Test: Removed pinning of distro version on Travis to Ubuntu xenial (16.04) for Python 3.7, because that is now the default distro version, in order to pick up a future increase of the default distro version automatically.
pywbem 0.14.3¶
Released: 2019-05-30
Bug fixes:
- Windows install: Upgraded version of Win32/64OpenSSL.exe that is downloaded during installation on native Windows, from 1.1.0j to 1.1.0k. This became necessary because the maintainer of the Win32OpenSSL project at https://slproweb.com/products/Win32OpenSSL.html removes the previous version from the web site whenever a new version is released, causing the pywbem installation to fail during invocation of pywbem_os_setup.bat on Windows. Related to that, fixed the way pywbem_os_setup.bat recognizes that the version does not exist. (see issue #1754)
Enhancements:
Docs: Updated the trouble shooting section with an entry that explains how a user can resolve the installation failure that is caused on Windows when the Win32OpenSSL project at https://slproweb.com/products/Win32OpenSSL.html removes the previous version from their web site when a new version is released.
Increased versions of the following packages to address security vulnerabilities:
- requests from 2.19.1 to 2.20.1 (when on Python 2.7 or higher)
- urllib3 from 1.22 to 1.23
- bleach from 2.1.0 to 2.1.4
These packages are only used for development of pywbem.
Note that requests 2.19.1 has a security issue that is fixed in 2.20.0. However, requests 2.20.0 has dropped support for Python 2.6.
pywbem 0.14.2¶
Released: 2019-05-08
Bug fixes:
- Test: Temporary fix for pytest option –pythonwarnings in end2end tests (issue #1714).
- Test: Fixed AttributeError in end2end assertion functions (Issue #1714)
- Test: Added and fixed profile definitions for end2end tests. (Issue #1714)
- Fix issue in the Jupyter notebook iterablecimoperations where the IterQueryInstance example did not correctly processthe return from the operation. It attempted to itereate the returned object and should have been iterating the generator property in that object. Documentation of that example and the example were corrected. (see issue #1741)
- Fix issue in pywbem_mock/_wbemconnection_mock.py with EnumerateInstances that includes a property list with a property name that differs in case from the property name in the returned instance. Works in the conn_lite=True mode but fails in conn_lite=False mode because the test was case insensitive.
- Test: Fixed Appveyor CI setup for UNIX-like environments under Windows (Issue #1729)
Enhancements:
- Changed GetCentralInstances methodology in WBEMServer.get_central_instances() to be bypassed by default, because (1) WBEM servers do not implement it at this point, and (2) there are WBEM servers that do not behave gracefully when unknown CIM methods are invoked. Because WBEM servers are required to implement one of the other methodologies, this change is not incompatible for pywbem users.
- Improved the performance for receiving large CIM-XML responses in the tupleparser by moving type checks for text content in XML into an error handling path, and by replacing some isinstance() calls with type() comparison.
- Improved the quality of the information in TypeError exceptions that are raised due to invalid types passed in WBEMConnection operation arguments. (Issue #1736)
pywbem 0.14.1¶
Released: 2019-04-05
Bug fixes:
- Change history: Removed incorrect statement about commenting out server-specific functionality from the tuple parser from the change history of pywbem 0.14.0.
pywbem 0.14.0¶
This version contains all fixes up to pywbem 0.13.1.
Released: 2019-04-03
Bug fixes:
- Extend makefile clobber to remove cover files from pywbem_mock package.
- Fixed pip version issue on Appveyor.
- Fixed AttributeError on __offset in CIMDateTime.repr(). See issue #1681.
- Removed the associationDeclaration and IndicationDeclaration mof parser production rules from mof_compiler.py because: a) They were orderd in p_mp_createClass so that the classDeclaration production was always used, b) When reordered, they still created a YACC reduce/reduce conflict where the result was that YACC used the classDeclaration production to resolve the conflict, c) they represent exactly the same syntax as the classDeclaration. In effect, these production rules were never really used executed.
Enhancements:
- Significant performance improvements in the CIM-XML parser, resulting in about 50% elapsed time savings for 10000 returned CIM instances, compared to pywbem 0.13.0. See issue #1630.
- Added the possibility to specify a value of False for the embedded_object attribute/parameter of CIMProperty and CIMParameter. It is stored as None. The only difference to specifying None is that the embedded_object value is not inferred from the property or parameter value in that case, so this saves performance.
- Added the ‘python_requires’ keyword to the package definition, which makes pip aware of the supported Python versions.
- Refactored and extended Jupyter notebook for pywbem_mock.
pywbem 0.13.0¶
Released: 2019-02-23
This version contains all fixes up to pywbem 0.12.6.
Incompatible changes:
- Changed the path argument of CIMInstance to be deep copied, because it may be modified by setting properties. It was previously shallow copied (and incorrectly documented as not being copied). This is only incompatible if user code relies on the init method modifying the keybindings of its path input argument. If user code relies on that, it is highly recommended that you decouple such dependencies (Issue #1251).
- Changed the path argument of CIMClass to be shallow copied, in order to decouple the created object from its input arguments. It was previously not copied but referenced. This is only incompatible if user code relies on the init method modifying the provided path input argument. If user code relies on that, it is highly recommended that you decouple such dependencies (Issue #1251).
- Changed keybinding processing when creating CINInstanceName objects to disallow NULL keybinding values. This is in accord with the CIM standard DSP0004. This is only incompatible if user code relies on the non-standard behavior of creating a keybinding having None as a value. If your code relies on that non-standard behavior, it can be re-established by via the config property IGNORE_NULL_KEY_VALUE in config.py. Note that NULL keybindings may be an issue with some WBEM servers. (Issue #1298)
- The fix for issue #1302 removed the pywbem config variables from the pywbem namespace. They are now only available via the pywbem.config namespace. However, this change should not affect you because the previously documented approach for changing them through the pywbem namespace did not work, so if you changed the config variables successfully, you have done that through the pywbem.config namespace already, and this change does not affect you.
- Removed the ez_setup.py script from the repository. That script is the well-known tool that bootstraps easy_setup which was used for installing Python packages in times before pip became ubiquitous. If anyone still uses easy_setup these days for installing Python packages, it is time to switch to using pip. If you cannot do that for some reason, you will now need to install easy_setup by some other means.
- Changed CIMError exceptions raised to indicate incorrect CIM-XML responses to open/pull operations, to raise ParseError instead, consistent with other response checking (Issue #1320).
Deprecations:
- Added announcement that Python 2.6 support in pywbem will be removed in its future 1.0.0 version.
- Deprecated the tocimobj() function because it has some inconsistencies, in favor of the cimvalue() function introduced in pywbem 0.12.0. Changed all internal uses of tocimobj() to cimvalue(). (Issue #904).
- The deprecated internal methods imethodcall() and methodcall() of the WBEMConnection class will be removed in the next pywbem version after 0.13.
- Removed the deprecation for setting the default_namespace attribute of WBEMConnection that had been introduced in pywbem 0.12; setting it is now fully supported again.
Finalizations:
- Finalized the use_pull_operations property and init argument of the WBEMConnections class that allows controlling whether the Iter…() methods use pull operations or traditional operations.
- Finalized the logging support. The logging support was introduced in pywbem 0.11 and was redesigned in pywbem 0.12. For details, see the “WBEM operation logging” section in the pywbem documentation.
Bug fixes:
- Fixed the issue where wbemcli-help-txt was not being updated when wbemcli.py changed. (Issue #1205)
- Test: Fixed access to incorrect tuple members in run_cim_operations.py. that were used only in long version of the test. Found by Pylint. (Issue #1206).
- Fixed that CIMInstanceName.from_wbem_uri() did not support the representation of integer key values in binary, octal or hex format (part of Issue #904).
- Fixed an issue with running the tests on Travis CI that occurred on Python 2.6 with the latest package level and that was caused by the fact that a new version of the “httpretty” Python package was released that had dropped support for Python 2.6. This was fixed by limiting the version of httpretty to <0.9 when running on Python 2.6. Note that this only affects the development environment.
- Correct issue in pywbem_mock where we return incorrect CIMError (CIM_ERR_NOT_FOUND rather than CIM_ERR_METHOD_NOT_FOUND) when the class for a method is not defined in the methods repository. issue #1256
- Fixed issue in pywbem_mock where we were not creating deepcopy (we were using the pywbem .copy that is part of each object (see issue #1251) of objects returned from the repository so that if the objects were modified some of the changes bled back into the repository. Code modified to do deepcopy of everything inserted into the repository through add_cimobjects and the Create… methods and returned from the repository with any of the get/enumerate/etc. methods. We also modified code so that if there is a class repository there is also an instance repository even if it is empty. See issue #1253
- Fixed issue where pywbem_mock EnumerateClass and EnumerateClassNames parameter losing the ClassName parameter and no test for the ClassName parameter not existing in the repository. (See issue #1271)
- Correct issue in pywbem_mock where we return incorrect CIMError (CIM_ERR_NOT_FOUND rather than CIM_ERR_METHOD_NOT_FOUND) when the class for a method is not defined in the methods repository. issue #1256
- Fix issue causing pywbem_mock/_wbemconnection_mock.py display_repository() to display as bytes in Python 3. See issue # 1276
- Fixed the support for Unicode escape sequences in the MOF compiler. It supported only lower case x1234 but not upper case X1234. Also, it tolerated an invalid x escape sequence, when DSP0004 requires 1..4 hex characters to be present. See issue #1278.
- Fixed issue where Null key values allowed. See issue #1298
- Fixed issue with updating pywbem config variables. So far, the pywbem config variables were defined in the pywbem.config namespace and then imported by pywbem into the pywbem namespace. Pywbem documented that these config variables should be accessed (read and written) through the pywbem namespace. However, pywbem code read them in nearly all cases from the pywbem.config namespace. This caused an update that is done by a pywbem user through the pywbem namespace, not to be visible in the pywbem.config namespace, so pywbem did not react to the user’s change. This was fixed by only using the pywbem.config namespace for config variables. They are no longer imported into the pywbem namespace. See issue #1302.
- Fixed issue where the tomof() methods of CIMProperty, CIMQualifier, and CIMQualifierDeclaration raised IndexError when the value was an empty array. This issue perculated up to higher level CIM objects that are using these objects, i.e. CIMInstance or CIMClass. Added according testcases. See issue #1312.
- Fix issue in IterQueryInstances where the QueryLanguage and Query parameters were reveresed in the fallback call to ExecQuery method. See issue # 1334.
- Fixed the issue that the VALUE.OBJECTWITHLOCALPATH element was not allowed as a child element under IRETURNVALUE. This element is used as one possibility for the result of the ExecQuery operation. See issue #1347.
- Fixed issue in run_cimoperations.py with test for deep inheritance on EnumerateInstances. It was reporting confused result so we created a simpler test. See issue #477.
- Fixed issues in pywbem_mock where classnames on the operation requests were not treated as case insensitive for some operations, in particular the enumerate operations, reference operations, and associator operations. This also adds a number of tests to validate that classnames. See issue #1355.
- Fixed the issue that INSTANCE child elements on a returned ERROR element were not allowed. INSTANCE child elements are now allowed and will appear to the user as a list of CIMInstance objects in a new instances property of the CIMError exception that is raised. See issue #1380.
- Fixed issue in mof_compiler search_paths where doc defined iterable as input but since string is an interable it was allowed but misused. Extended code to specifically allow single string on input. See issue #1227.
- Increased the minimum required versions of the following dependent Python
packages in order to fix security issues with these packages:
- requests from 2.12.4 to 2.19.1
- html5lib from 0.9999999 to 0.999999999
- mistune from 0.7.3 to 0.8.1
- The ValueMapping class only supported decimal representations of integer values in the ValueMap qualifier. However, DSP0004 allows for decimal, binary, octal and hexadecimal representations of integer values. Added support for all these representations to the ValueMapping class. See issue #1547.
- Multiple fixes in WBEMServer.get_central_instances():
- For a profile that implements the central class methodology but has no central instances, the implementation went on to try the scoping class methodology. Now, it accepts that as a valid central instance implementation and returns an empty list of instances, instead. Non-implementation of the central class methodology is not detected from CIM_ERR_NOT_SUPPORTED being returned on the Associators operation that attempts to traverse the CIM_ElementConformsToProfile association.
- For a profile that implements the scoping class methodology, the traversal from the profile side to the resource side incorrectly assumed that for multi-hop scoping paths, the hops above the first hop could be used as the scoping path of the scoping profile. That has been changed to now omit the scoping path when invoking get_central_instances() on the scoping profile. As a result, the scoping profile is now required to implement the central class methodology.
- For a profile that implements the scoping class methodology, the traversal from the central instances of the scoping profile down to the central instances of the original profile incorrectly only traversed the first hop of the reversed scoping path. This has been fixed to traverse the entire reversed scoping path.
- In the recursive invocation of get_central_instances() for the scoping profile, the newly introduced reference direction was not passed on. For now, it is assumed that the scoping profile has the same reference direction as the original profile.
- Because it seems that with these bugs, the get_central_instances() method cannot have been used reasonably, some ValueError exceptions` it returned to indicate server implementation issues, have been changed to use the newly introduced ModelError exception.
- For Python 2.6, pinned version of lxml to <4.3.0, because lxml 4.3.0 has removed support for Python 2.6. See issue #1592.
- Fixed the URL on the DMTF site from which the MOF archive is downloaded. This has changed on the DMTF site and needed to be adjusted.
- Fixed order of parameters in example method_callback_interface defined in pywbem_mock FakedWBEMConnection. (See issue #1614)
- Fixed an error “Python : can’t open file ‘C:Usersfirstname’ : No such file or directory” when invoking wbemcli.bat on native Windows in a directory whose path name contained blanks. (See issue #1622)
- Extend pywbem_mock to correctly handle resolving of classes when they are inserted into the repository. Resolving of classes configures a class inserted with CreateClass or through the mocker add_cimobjects, etc. to reflect the inheritance of properties, methods, etc. from the superclass. The initial release did a very abbreviated resolution which left some characteristics of the new class and did not properly handle things like the override qualifier. (See issue # 1540). This change also simplifies the mocker in that both the compiler and the mock responder methods contribute to the same repository (the original version copied objects from the compiler repository to the mocker repository).
- Test: Fixed a bytes/unicode error in validate.py that occurred on Python 3 when xmllint failed validating the DTD.
- Increased the minimum M2Crypto version to 0.31.0 in order to pick up the fix for pywbem issue #1275 (incorrect timeout value).
- Added the Pyton tox package to the dependencies for development.
Enhancements:
Extend pywbem MOF compiler to search for dependent classes including:
- reference classes (classes defined in reference properties or parameters)
- EmbeddedInstance qualifier classes if they are not compiled before the classes that reference them are compiled. Previously the lack of these dependent classes was ignored. The compiler already searches for superclasses if they are not compiled before their subclasses.
Extends MOFWBEMConnection to generate an exception if the compile of a class with reference parameters or properties reference class is not in the repository or if the class defined for an EmbeddedInstance qualifier is not in the repository.
This uses the capability in the MOF compiler to search the defined search path for the missing classes if they are not in the repository.
This means that the mof_compiler can be used to create a complete class repository builds without having to specifically declare all dependent classes for the classes the user needs in a repository if the mof for the dependent classes in in the search path. (Issue #1160).
Made CIMInstanceName.from_wbem_uri() and CIMClassName.from_wbem_uri() more flexible w.r.t. tolerating non-standard WBEM URIs that omit the leading colon before class names (part of Issue #904).
Added a tobinary() method to the ValueMapping class, which translates the value mapping from a Values string to binary integer values, or a range thereof. This is the opposite direction of the existing tovalues() method. (Issue #1153)
Added an items() generator method to the ValueMapping class for iterating through the items of the value mapping, returning tuples of the binary value (or a range thereof), and the Values string. (Issue #1153)
Docs: Clarified that the copy() methods of NocaseDict and of the CIM object classes produce middle-deep copies, whereby mutable leaf attributes are not copied and thus are shared between original and copy (Issue #1251).
Docs: Added a note to the description of the copy() methods of the CIM objects that states that copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies (Issue #1251).
Extend wbemcli to use pywbem_mock with a new command line parameter (–mock_server <mock_info-filename>). Added a set of new tests for this parameter and a MOF file and test code to test the new option. (Issue #1268)
Installation on Windows is now more automated by means of a new pywbem_os_setup.bat script. As part of that, the latest M2Crypto version 0.30.1 is now used on Windows, and no longer the somewhat aged versions in the M2CryptoWin32/64 packages. For details, see the installation section in the documentation. That script also downloads and installs Win32 OpenSSL from https://slproweb.com/products/Win32OpenSSL.html.
Made exception messages more explicit in the ValueMapping and WBEMServer classes. Issue #1281.
Docs: Added a shell command for determining the version of an installed pywbem package, that covers all released pywbem versions (Issue #1246).
Docs: Added jupyter notebooks to demonstrate use of pywbem_mock.
Make: Eliminated the confusing but unproblematic error message about pbr importing when running certain make targets in a freshly created Python environment. Issue #1288.
In MOFCompiler.__init__(), added a type check for the search_paths parameter to avoid accidential passing of a single string. Issue #1292.
Add new static method to CIMInstance (from_class) that builds an instance from a class and dictionary of property values. Issue #1188
Added support for tolerating a TYPE attribute in the PARAMVALUE element of received CIM-XML responses. The TYPE attribute is not allowed as per DSP0201. However, there are devices that have incorrectly implemented a TYPE attribute instead of the standard PARAMTYPE attribute. The TYPE attribute when present is now used when PARAMTYPE is not present. If both are present, PARAMTYPE is used and TYPE is ignored. Also, test cases were added for tupleparse for the PARAMVALUE element. See issue #1241.
Added support for automatically creating the Pragma: UpdateExpiredPassword HTTP header in the CIM-XML request if pywbem detects that the special SFCB method “UpdateExpiredPassword()” is invoked on class “SFCB_Account”. SFCB requires this HTTP header for that method. See https://sblim.sourceforge.net/wiki/index.php/SfcbExpiredPasswordUpdate for details about this SFCB functionality. The automatic creation of the header field is enabled by default and can be disabled with a new pywbem config variable AUTO_GENERATE_SFCB_UEP_HEADER. See issue #1326.
Add support for ExecQuery (shortcut eqy) to wbemcli. See issue # 1332.
Added support for a new WBEM URI format “canonical” to the to_wbem_uri() methods of CIMInstanceName and CIMClassName. The new format behaves like the existing format “standard”, except that case insensitive components are translated to lower case, and the order of keybindings is the lexical order of the lower-cased key names. The new format guarantees that two instance paths or class paths that are equal according to DSP0004, return equal WBEM URI strings. See issue #1323.
Added support for Python 3.7, which was released 2018-06-27.
Enhanced the output of the string representation of the CIMError exception by adding the status code name (e.g. the string “CIM_ERR_NOT_SUPPORTED” for status code 7). The string representation is used for example when showing the exception in a Python traceback. See issue #1350.
Added checking for the returned instance name to the CreateInstance operation. This changes the exception that is raised from TypeError or IndexError indicating an internal issue, to several pywbem.ParseError exceptions that have reasonable error messages. Note that there is an uncertainty as to whether DSP0200 would allow CreateInstance to not return an instance name. Because this would already have caused an exception to be raised in the current pywbem code, it is assumed that all WBEM server implementations so far always return the instance name, and therefore, pywbem has just improved the quality of the exception that is raised, and continues not to tolerate a missing instance name. Extended the testcases for CreateInstance accordingly. See issue #1319.
Added support for CIM namespace creation via a new WBEMServer.create_namespace() method. See issue #29.
Added support for CIM namespace deletion via a new WBEMServer.delete_namespace() method. See issue #1356.
Added connection information to all pywbem exceptions. This is done via a new optional conn_id keyword argument that was added to all pywbem exception classes. The exception message now has a connection information string at its end. See issue #1155.
Added support for passing a WBEMConnection object for the handle parameter of the MOFCompiler creation. This allows a user to pass the WBEM connection directly as a CIM repository, without first having to create a MOFWBEMConnection object.
Made the namespace handling in the pywbem mock support explicit. It is now required to add any namespaces to the mock registry in a FakedWBEMConnection object. A method add_namespace() has been added for easy setup of the mock repository w.r.t. namespaces. The default namespace of the connection is added automatically when creating a FakedWBEMConnection object.
Extended the support for handling namespace creation in the faked CreateInstance operation to support CIM_Namespace in addition to PG_Namespace, and improved it to properly reflect the created namespace in the mock repository.
Added support for handling namespace deletion in the faked DeleteInstance operation for creation classes CIM_Namespace and PG_Namespace.
Added support for asterisks in CIM datetime values to the pywbem.CIMDateTime class, as defined in DSP0004 for representing insignificant digits. Changed the format returned by its __repr()__ method so that it now shows its internal attributes and no longer the string representation of the value. Added a __repr__() method to the pywbem.MinutesFromUTC class that shows its internal attributes. See issue #1379.
Added an instances property to the CIMError exception class that can be used to represent a list of error instances returned by the WBEM server in error responses. See issue #1380.
Pywbem now ensures that when specifying the default_namespace argument of WBEMConnection() as None, or when setting the default_namespace attribute of an already existing WBEMConnection object to None, that it is set to the built-in default namespace “root/cimv2”, instead. Previously, that was done only when not specifying the default_namespace argument.
All exception and warning messages produced by pywbem now are guaranteed to contain only ASCII characters. Unicode characters in the messages are represented using an escape syntax such as \uXXXX or \U00XXXXXX. That was also done for the result of any __repr__() methods of pywbem. This is important in order to avoid secondary Unicode encoding exceptions while a first exception or warning is processed. See issue #1072.
Docs: Added summary tables for public methods and public attributes exposed by classes defined by the “pywbem” and “pywbem_mock” Python packages, including any methods and attributes inherited from base classes. See issue #1417.
Improved the brand and version attributes of the WBEMServer class so that they produce reasonable results for more types of WBEM servers than just OpenPegasus and SFCB. The WBEM servers that are now recognized, are:
"OpenPegasus"
"SFCB"
(Small Footprint CIM Broker)"WBEM Solutions J WBEM Server"
"EMC CIM Server"
"FUJITSU CIM Object Manager"
See issue #1422.
Added __str__() methods to the WBEMServer, WBEMListener, and WBEMSubscriptionManager classes in order to reduce the amount of information. Previously, this defaulted to the result of __repr__(). See issue #1424.
Improved the quality of any ParseError exception messages when the SAX parser detects errors in CIM-XML responses. See issue #1438.
Added a ToleratedServerIssueWarning class and its base class Warning. The new ToleratedServerIssueWarning is raised in cases when the WBEM server exhibits some incorrect behavior that is tolerated by pywbem.
Added a ModelError exception class that indicates an error with the model implemented by the WBEM server, that was detected by the pywbem client.
Added support for tolerating ill-formed XML in the CIM-XML response returned by the server from the attempt to invoke the CIM method GetCentralInstances() inside of WBEMServer.get_central_instances(). One server was found to return such ill-formed XML. This now causes pywbem to issue a ToleratedServerIssueWarning and to continue with the next approach for determining the central instances. See issue #1438.
The last_raw_request and last_raw_reply properties of WBEMConnection had previously only been set when debug was enabled on the connection. They are now always set. This was needed to support tolerating ill-formed XML, and does not cost any additional conversions. See issues #1438 and #1568.
In the WBEMServer class, the Interop namespace is now added to the set of namespaces in the namespaces property, if missing there. This accomodates the behavior of a particular WBEM server that was found to support the Interop namespace without representing it as a CIM instance. See issue #1430.
Added support for specifying the reference direction in WBEMServer.get_central_instances() by adding an optional parameter reference_direction. This was necessary because the DMTF ‘Profile Registration Profile’ (PRP) and the SNIA PRP use the CIM_ReferencedProfile association class in opposite ways: The DMTF PRP defines that the ‘Dependent’ end of that class goes to the referencing profile which is defined to be the autonomous profile, while the SNIA PRP defines that the ‘Antecedent’ end goes to the autonomous profile. See issue #1411.
In order to be able to distinguish errors at the CIM-XML level (e.g. required attribute missing on an XML element) and at the XML level (e.g. ill-formed XML), two subclasses of the ParseError exception have been added: CIMXMLParseError and XMLParseError, that are now raised instead of ParseError. Because these are subclasses, this change is backwards compatible for users that have caught ParseError. The new subclasses have the CIM-XML request and response data available as properties.
The WBEMServer.get_selected_profiles() method has been changed to match the registered names, organisations and versions of profiles case insensitively, in order to better deal with profile name changes in SMI-S. See issue #1551.
Docs: Clarified in the WBEMServer.get_central_instances() method that all profiles scoped by a top-level specification or autonomous profile implement the same reference direction (‘snia’ or ‘dmtf’).
Docs: The WBEMServer.get_central_instances() method had a description of the profile advertisement methodologies that was hard to understand without knowledge of some of the related DMTF standards. Changed that to make it understandable for pywbem users without requiring knowledge of these documents. Some of the text has been moved to a new section “Profile advertisement methodologies” in the Appendix of the pywbem documentation. As part of that, clarified how to determine the scoping class and scoping path for a component profile that does not specify them in the profile description. See issue #1398.
Corrected the hint how to exit in wbemcli when running on Windows.
Added method to statistics (class Statistics, method reset()) to reset the statistics on a WBEMConnection. This simply resets all of the statistics values gathered on that connection to their initial values.
Cleanup:
- Moved class NocaseDict into its own module (Issue #848).
- Resolved several Pylint issues, including several fixes (Issue #1206).
- Cleanup mof_compiler use of args[0] and args[1] with CIMError. (Issue #1221)
- Removed one level of superflous copies of dictionaries in the copy() methods of the CIM object classes. These dictionaries are already copied in the setter methods for the respective attributes (Issue #1251).
- Added and improved CIM-XML response checks at operation level (Issue #919).
- Changed some warnings classified as UserWarning to be classified as pywbem.ToleratedServerIssueWarning, because that better fits the nature of the warnings. See issue #1595.
- Removed the Connection ID from any exception and warning messages, so that Python warnings about the same thing are now properly folded together into one warning during end2end tests. The exception objects still contain the connection ID as a property conn_id, and the pywbem log also still shows the connection ID for each entry. See issue #1589.
Build, test, quality:
- Add tests for the WBEMSubscriptionManager class using the pywbem mock support. This involved changing the tests for the WBEMServer class using pywbem_mock because the the WBEMSubscriptionManager class depends on the existence of the classes and instances that support the pywbem WbemServer class existing in the WBEM server. A new file (wbemserver_mock.py) was added to the tests that creates the pywbem_mock for any tests that depend on classes like CIM_Namespace, CIM_ObjectManager existing in the mocked server. See issue #1250
- Needed to upgrade PyYAML version from >=3.12 to >=3.13 due to an issue in PyYAML on Python 3.7, that was fixed in PyYAML 3.13. See issue #1337.
- Pinned the version of the pytest-cov package to <2.6 due to the fact that pytest-cov 2.6.0 has increased its version requirement for the coverage package from coverage>=3.7.1 to coverage>=4.4. That is in conflict with the version requirement of python-coveralls for coverage==4.0.3. This is only a workaround; An issue against python-coveralls has been opened: https://github.com/z4r/python-coveralls/issues/66
- Reorganized the testsuite directory to better separate unit tests, function tests, end2end tests, and the tested areas (pywbem, pywbem_mock, and test utility functions). The new top level test directory is now named tests and the new directrory structure is documented in section “Testing” in the development section of the pywbem documentation and in the file tests/README.
- Added the concept of end2end tests for pywbem. The end2end tests execute test files named test_*.py within the tests/end2endtest directory against groups of real WBEM servers defined by a WBEM server definition file in YAML syntax: tests/server_definitions/server_definition_file.yml. There is an example file example_server_definition_file.yml. There are some initial tests, and users can define their own tests.
- For the end2end tests, added a file tests/profiles/profiles.yml that defines the discovery-related characteristics of a number of DMTF and SNIA management profiles, and that is used to drive profile discovery related tests against WBEM servers.
- Added toleration support in the CIM-XML response parsing for WBEM servers that return attribute TYPE with an empty string instead of omitting it. As part of that, improved the checking for valid values of the TYPE attribute. See issue #1564.
- Improved testing of the tocimxml() and tocimxmlstr() methods of the CIM object classes (e.g. CIMinstance) by adding validation against the CIM-XML DTD, and by adding tests for the indent parameter of tocimxmlstr().
- Added support for running pylint also on Python 3.x. See issue #1640.
- Improved the makefile for use on native Windows. See issue #1631. Details:
- Some GNU make versions on native Windows have an issue with double quotes in make $(shell ..) commands; removed the use of double quotes. As a result, most inline python commands have been moved into new small scripts in the tools directory. Also, several make targets that used to produce log files, no longer can do that and the user needs to redirect the make invocation in order to get a log file.
- Removed dependencies on most UNIX-like commands (touch, tee, bash, rm, find, xargs) when using make on native Windows.
- Encapsulated file removal and copy commands to be compatible between native Windows and other platforms.
- Updated the appveyor.yml file to check only the new, smaller, list of commands.
pywbem 0.12.0¶
Released: 2018-04-11
Incompatible changes:
Finalized the Iter support that was experimental so far. This affects the Iter…() methods of class WBEMConnection, the use_pull_operations init parameter and instance attribute of class WBEMConnection, and the iter-related shortcuts in the wbemcli script.
The following initialization parameters of some CIM object classes that are required not to be None (as per the documentation) are now enforced not to be None, and ValueError is now raised when providing them as None:
- CIMInstanceName.classname (already raised ValueError)
- CIMInstance.classname
- CIMClassName.classname (previously raised TypeError)
- CIMClass.classname
- CIMProperty.name (already raised ValueError)
- CIMMethod.name (previously raised TypeError)
- CIMParameter.name
- CIMParameter.type
- CIMQualifier.name
- CIMQualifierDeclaration.name
- CIMQualifierDeclaration.type
Unless otherwise noted, the previous behavior was to tolerate None.
Note that in all cases, the requirement not to be None had previously been documented.
When setting some attributes of CIM object classes that are required not to be None (as per the documentation), ValueError is now raised when attempting to set them to None:
- CIMInstanceName.classname
- CIMInstance.classname
- CIMClassName.classname
- CIMClass.classname
- CIMProperty.name
- CIMMethod.name
- CIMParameter.name
- CIMParameter.type
- CIMQualifier.name
- CIMQualifierDeclaration.name
- CIMQualifierDeclaration.type
The previous behavior was to tolerate None.
Note that in all cases, the requirement not to be None had previously been documented.
When initializing objects of the CIM object classes CIMProperty and CIMQualifier with a type parameter of None, and when initializing the properties of CIMInstance, their CIM type is (and has previously been) inferred from the value.
If inferring the type is not possible (for example because the value is a Python integer, float, long (Python 2 only), or None), the exception that is raised is now ValueError. Previously, TypeError was raised in that case.
When setting the type attribute of the CIM object classes CIMProperty and CIMQualifier, the type is now enforced not to be None, and ValueError is raised when providing it as None.
Previously, setting a type of None was tolerated.
Note that in both cases, the requirement not to be None had previously been documented.
For CIM elements passed as dictionaries into CIM object classes (i.e. the aparameters/attributes properties, keybindings, parameters, qualifiers), the consistency between the dictionary key and the name of the CIM object that is the dictionary value is now checked and ValueError is raised if it does not match (case insensitively).
Initializing a CIMProperty object as an embedded object or embedded instance and with a value of None now requires specifying type=”string”.
Previously (but only starting with pywbem 0.8.1), the type was inferred from the embedded_instance parameter and thus could be omitted. This new requirement for specifying type is not really intentional, but a by-product of simplifying the implementation of CIMProperty. It was considered acceptable because that should not be a common case (and has not been supported before pywbem 0.8.1 anyway).
When converting a CIMInstance object to CIM-XML using its tocimxml() method, instance properties whose values are simple types instead of CIMProperty objects are no longer converted into CIMProperty objects because that has worked only for a very limited set of cases, and because they are required to be CIMProperty objects anyway. A TypeError is now raised if that is detected.
The atomic_to_cim_xml() function now raises TypeError if it cannot convert the input value. Previously, it used str() on the input value as a last resort.
The global tocimxml() function now raises TypeError if it cannot convert the input value. Previously, it raised ValueError.
The CIMQualifierDeclaration.tomof() method now generates the flavor keywords only if the tosubclass and overridable attributes are set to True or False. Previously, default keywords were generated when these attributes were set to None (and these defaults were the opposite of the defaults defined in DSP0004 and DSP0201). The new behavior is consistent with the definition that None for these attributes means the information is not available, and it is also consistent with the tocimxml() method. If you used this method and relied on the defaults being generated, you will now have to set these attributes explicitly.
If a WBEM server specifies contradicting TYPE and VALUETYPE attributes on a KEYVALUE element returned to the client (this element is used in instance paths, e.g. for the result of the EnumerateInstanceNames operation), TYPE now takes precedence. Previously, VALUETYPE took precedence. DSP0201 leaves the handling of such discrepancies open, and it seems more logical to let the more precise value take precedence. Because WBEM servers are required to specify consistent values for these attributes, this change should not affect users of pywbem.
Values of CIM type ‘reference’ in CIM objects (CIMProperty, CIMParameter, CIMQualifier, and CIMQualifierDeclaration) may now be CIMClassName objects (i.e. class paths). This has been changed for consistency with DSP0201 (Issue #1035).
Renamed the enable_stats init argument of class WBEMConnection to stats_enabled, as part of its finalization. It was experimental, before. (Issue #1068).
Renamed the -e, –enable-stats options of the wbemcli utility to –statistics , as part of its finalization. It was experimental, before. (Issue #1068).
Changed the WBEMConnection attributes for the last request and last response to become read-only (last_request, last_raw_request, last_reply, last_raw_reply). They have never been supposed to be writeable by users. (Issue #1068).
In the wbemcli shell, renamed the following function parameters. This is only relevant if you wrote scripts against the shell and named these parameters: (Issue #1110).
- The “op” parameter of iter functions that have it was renamed to “ip”, because it is always an instance path.
- The “qi” parameter of the query functions was renamed to “qs”, for consistency with the filtering functions.
- The “fq” parameter of the filtering functions was renamed to “fs”, for consistency with the query functions.
Revamped the (experimental) logger configuration mechanism completely. It remains experimental. See issue #859. The changes include:
- Created 3 methods in WBEMConnection that allow pywbem logs to be configured and activated. These methods contain parameters for: a. configuring the Python loggers for either/or/both the api and http loggers. b. Setting the level of detail in the log output. c. Activating each logger within WBEMConnection.
- Allow for the standard Python loggers to be used to configure logger names that will be used by the pywbem loggers. This allows the pywbem loggers to be compatible with user code that creates their specific logger configurations.
- Eliminated the PyWBEMLogger class that was the original logging setup tool in pywbem 0.11.0 since its use was incompatible with using standard Python logging configuration methods to define loggers.
- Created a function in the _logging module that allows pywbem logging to be defined by a single string input.
- Addition of a new property conn_id to WBEMConnection which is a unique identifier for each WBEMConnection object and is part of each log record. This allows linking logs for each WBEMConnection in the log.
Deprecations:
- Deprecated modifications of the connection-related attributes of WBEMConnection objects (Issue #1068).
- Deprecated the value None for the value argument of pywbem.tocimxml(), because it generates an empty VALUE element (which represents an empty string) (Issue #1136).
Enhancements:
- Finalized the time statistics support that was experimental so far. This affects classes OperationStatistic, Statistics, the init argument enable_stats of class WBEMConnection, and the properties stats_enabled, statistics, last_operation_time, and last_server_response_time of class WBEMConnection. As part of that, renamed the enable_stats init argument to stats_enabled, consistent with the corresponding property.
- For CIMInstanceName, the values of keybindings can now be specified as CIMProperty objects from which their value will be used (this is in addition to specfying the values of keybindings as CIM data types).
- For CIMInstanceName, values of keybindings specified as binary strings are now converted to Unicode.
- For CIMInstanceName, the type of the input keybindings is now checked and TypeError is raised if the value is not a CIM data type.
- Updating attributes of CIM objects (e.g. updating CIMInstance.properties) now goes through the same conversions (e.g. binary string to unicode string) as for the same-named constructor parameters. As a result, it is ensured that all attributes that are strings (e.g. name) contain unicode strings, all attributes that are booleans (e.g. propagated) contain bool values, and all CIM values (e.g. CIMProperty.value) are of a CIM data type.
- Added static from_wbem_uri() methods to CIMInstanceName and CIMClassName, that create a new object of these classes from a WBEM URI string.
- Added a cimvalue() function that converts input values specified at the interface of CIM object classes, into the internally stored CIM value. It is mainly used internally by the CIM object classes, but has also been made available at the public API of pywbem. Its functionality is very close to the existing tocimobj() function.
- Changed public attributes to Python properties with getter and setter methods in all CIM object classes (e.g. CIMInstance). This allows normalizing and applying checks for new values of these properties. In addition, it solves the Sphinx warnings about duplicate ‘host’ attribute when building the documentation (issue #761).
- Added catching of some exceptions M2Cryptro can raise that were not caught so far: SSL.SSLError, SSL.Checker.SSLVerificationError. These exceptions are now transformed into pywbem.ConnectionError and will therefore be caught by a caller of pywbem who is prepared for pywbem’s own exceptions, but not necessarily aware of these M2Crypto exceptions. (issue #891)
- Added the catching of a httplib base exception to make sure all httplib exceptions are surfaced by WBEMConnection methods as a pywbem.ConnectionError (issue #916).
- In the tomof() methods of the CIM object classes, changed the formatting of the generated MOF to be more consistent with the CIM Schema MOF.
- Added new methods CIMInstanceName.to_wbem_uri() and CIMClassName.to_wbem_uri() that return the path as a WBEM URI string that conforms to untyped WBEM URIs as defined in DSP0207. The CIMInstanceName.__str__() and CIMClassName.__str__() methods still return the same WBEM URI string they previously did, but that is a historical format close to but not conformant to DSP0207 (issues #928, #943).
- Improved the way CIM-XML parsing errors are handled, by providing the original traceback information when re-raising a low-level exception as pywbem.ParseError, and re-established the improved exception message for invalid UTF-8 and XML characters that was broken since the move to using the SAX parser.
- Added support for properly hashing CIM objects (CIMClass, etc.) and CIM data types (particularly CIMDateTime), as long as these (mutable) objects are not changed. Because the objects must not be changed while being in a set, a new term “changed-hashable” has been introduced that describes this. This allows to have CIM objects in sets such that they behave as one would expect from a set. Previously, two CIM objects that were equal could both be in the same set, because their hash value was different. In the documentation, added a new section “Putting CIM objects in sets” that explains the considerations when utilizing the hash value of the mutable CIM objects.
- Added support for retrieving the operation recorders of a connection via a new operation_recorders read-only property (Issue #976).
- Extended CIMParameter to represent CIM parameter values in method invocations. As part of that, removed the deprecation from its value property and added an embedded_object property. Extended the testcases accordingly. Added an as_value argument to CIMParameter.tocimxml() and to tocimxmlstr() to allow control over whether the object is interpreted as a value or as a declaration. (Issue #950).
- Added a new conversion function to the public API: cimtype() takes a CIM data typed value (e.g. Uint8(42)) and returns the CIM data type name for it (e.g. “uint8”). Previously, this was an internal function (Issue #993).
- Added a new conversion function to the public API: type_from_name() takes a CIM data type name (e.g. “uint8”) and returns the Python type representing that CIM data type (e.g. Uint8). Previously, this was an internal function (Issue #993).
- Extended WBEMConnection.InvokeMethod() to accept an iterable of CIMParameter objects as input parameters, in addition to the currently supported forms of input parameters. This allows specifying the embedded_object attribute (instead of inferring it from the value). (Issue #950).
- Docs: Improved the descriptions of CIM objects and their attributes to describe how the attributes are used to determine object equality and the hash value of the object.
- The child elements of CIM objects (e.g. properties of CIMClass) now preserve the order in which they had been added to their parent object. Methods such as tomof(), tocimxml(), and to_wbem_uri() now output the child elements of the target object in the preserved order. If a child element is initialized with an object that does not preserve order of items (e.g. a standard dict), a UserWarning is now issued.
- Added a new kind of input object for initializing CIM objects: An iterable of the desired CIM object type, and documented the already supported iterable of tuple(key, value) as a further input type.
- Improved checking of input objects when initializing a list of child elements in a CIM object(e.g. properties of CIMClass), and raise TypeError if not supported.
- Made the ValueMapping class more generally available and no longer tied to the WBEMServer class. It is now described in the “Client” chapter of the documentation, and it is possible to create new ValueMapping objects by providing a WBEMConnection object (as an alternative to the WBEMServer object that is still supported, for compatibility). Issue #997.
- Extended the ValueMapping class; its objects now remember the context in which the value mapping is defined, in terms of the connection, namespace, class, and of the mapped CIM element (i.e. property, method or parameter).
- Extended the ValueMapping class by adding a __repr__() method that prints all of its attributes, for debug purposes.
- Added capability to mock WBEM Operations so that both pywbem and pywbem users can create unit tests without requiring a working WBEM Server, This feature allows the user to create CIM objects in a mock WBEM Server defined with the class FakedWBEMConnection and substitute that class for WBEMConnection to create a mock WBEM Server that responds to wbem operations. This enhancement is documented in the pywbem documentation section 10, Mock Support. See issue #838.
- Improved the messages in ParseError exceptions raised when parsing CIM-XML received from a WBEM server.
- The type of keybinding names in CIMInstanceName objects is now checked to be a string (or None, for unnamed keys). The requirement for a string has always been documented. This was changed as part of addressing issue #1026.
- Fixed the support for unnamed keys (i.e. instance paths with KEYVALUE or VALUE.REFERENCE elements without a parent KEYBINDINGS element). DSP0201 allows for this as a special case. (Issue #1026).
- Added support for instance qualifiers when parsing received CIM-XML responses (Issue #1030).
- CIM data type names specified for the type or return_type parameter of CIM objects are now checked for validity, and ValueError is raised if not valid (Issue 1043).
- Added a new method CIMInstanceName.from_instance() to create CIMInstanceName objects from class and instance. This was done as part of building the pywbem_mock environment. See issue #1069.
- The url property of WBEMConnection now transforms its input value to unicode. (Issue #1068).
- In the WBEMListener class, added support for using it as a context manager in order to ensure that the listener is stopped automatically upon leaving the context manager scope.
- In the WBEMListener class, added properties http_started and https_started indicating whether the listener is started for the respective port.
- CIMInstance.tocimxml()/tocimxmlstr() were extended to allow controlling whether the path is ignored even if present. This capability is used for ignoring the path in embedded instance parameter values (as part of fixing issue #1136).
- CIMInstanceName/CIMClassName.tocimxml()/tocimxmlstr() were extended to allow controlling whether the host and namespace are ignored even if present. This capability is not currently used but was introduced for consistency with ignoring the path on CIMInstance.tocimxml()/tocimxmlstr() (as part of fixing issue #1136).
- Improved the handling of certain connection errors by retrying and by issuing user warnings instead of printing if debug. (Issue #1118).
Bug fixes:
Added libxml2 operating system package as a dependency. It provides xmllint, which is used for testing.
Fixed issue where MOFCompiler.compile_str() could not compile MOF that was defined through a MOF file containing #pragma include statements. This precluded using a string to define the classes to include in a mof compile in a string and required that the include be a file. See issue #1138.
Fixed issue in IterReferenceNames and IterAssociatiorNames where it was not passing the IncludeQualifiers input parameter to the OpenReferenceNames operation. This should not have been a significant issue since in general qualifiers are not parts of instances. See issue #833.
Also changed code in IterQueryInstances were parameters that are required by the called ExecQuery and OpenQueryInstances were defined as named arguments where since they are required, the name component is not required. This should not change operations except that when we were mocking the methods, it returns sees the parameter as name=value rather than value. See issue #833.
Fixed the bug that CIMInstanceName.tocimxml() produced invalid CIM-XML if a keybinding value was set to an invalid CIM object type (e.g. to CIMParameter). The only allowed CIM object type for a keybinding value is CIMInstanceName, for keys that are references. Now, TypeError is raised in that case.
Fix issues in cim_operations.py where a open or pull that returned with missing enumeration_context and eos would pass one of the internal tests. See issue #844
Fixed an error in the CIM-XML representation of qualifier values where the values were not properly converted to CIM-XML. They are now properly converted using atomic_to_cim_xml().
Fixed local authentication for OpenWBEM and OpenPegasus. Due to one bug introduced in pywbem 0.9.0, it was disabled by accident. A second bug in local authentication has been there at least since pywbem 0.7.0.
Fixed missing exception handling for CIM-XML parsing errors when parsing embedded objects. This could have caused low-level exceptions to be raised at the pywbem API.
Fixed the problem that a for-loop over CIMInstance / CIMInstanceName objects iterated over the lower-case-converted property/key names. They now iterate over the names in their original lexical case, as documented, and consistent with the other iteration mechanisms for CIM objects. The test cases that were supposed to verify that did not perform the correct check and were also fixed.
Fixed the bug that an (unsupported!) reference type could be specified for the return value of CIM methods, by raising ValueError if CIMMethod.return_value is initialized or set to “reference”.
Fixed issue introduced in mof_compiler when atomic_to_cimxml was cleaned up that did not allow using alias with some association classes. Also added test for this issue. See issue #936
Fixed the CIMInstanceName.__str__() and CIMClassName.__str__() methods to now return WBEM URI strings that are compliant to DSP0207. Changes include:
- Local WBEM URIs (i.e. when authority/host is not set) now have a leading slash. That leading slash was previously omitted.
- WBEM URIs with no namespace set now have a colon before the class name. Previously, the colon was produced only when a namespace was set.
Issue #928.
Fixed the comparison of CIMProperty objects to also consider the embedded_object attribute. Previously, this attribute was not considered, probably due to mistake (there is no reason not to consider it, as it is a user-provided input argument). Fixed the yaml testcases for embedded objects that failed as a result of that fix. These testcases did not set the embedded_object attribute to ‘object’, so it got its default value ‘instance’, which caused the testcases to fail. Needed to use the long form for specifying property values inthe yaml now, because the short form does not allow for specifying the embedded_object attribute.
Fixed the comparison of CIMProperty and CIMMethod objects to compare their class_origin attribute case-insensitively. If set, it contains a CIM class name. Previously, that attribute was compared case-sensitively.
Fixed the use of hard coded value limits in the ValueMapping class for open ranges of the ValueMap qualifier, by making them dependent on the data type of the qualified element. This only affected elements with data types other than Uint32 and only if the ValueMap qualifier defined open ranges whose open side reached the min or max limit (i.e. was first or last in the list). Extended the test cases to include this situation (Issue #992).
Fixed the lookup of the Values string for negative values in the ValueMapping class (found when solving #992).
Added support for octal, binary and hex numbers when parsing MOF using the MOFCompiler class, in compliance with DSP0004 (Issue #974). Extended the testcases to cover such numbers.
Fixed the issue that any use of CIMDateTime objects in the TestClientRecorder resulted in a RepresenterError being raised, by adding PyYAML representer and constructor functions that serialize CIMDateTime objects to YAML. Extended the testcases in test_recorder.py accordingly (Issues #702, #588).
Fixed an AttributeError when ValueMapping was used for methods, when an internal method attempted to access the ‘type’ attribute of the CIM object. For methods, that attribute is called ‘return_type’. Testcases for methods and parameters have now been added.
Fixed the issue that leading and trailing slash characters in namespace names were preserved. This was leading to empty NAMESPACE/NAME elements, which can be rejected by WBEM servers. Now, leading and trailing slash characters on namespace names are stripped off in pywbem before sending the request to the server. (Issue #255).
Fixed the issue that the parser for CIM-XML received from the WBEM server required the VALUETYPE attribute of the KEYVALUE element. DSP0201 defines VALUETYPE as optional, with a default of ‘string’. That is now implemented.
Fixed the issue that the parser for CIM-XML received from the WBEM server did not support hexadecimal representations of integers in the KEYVALUE element. They are now supported.
Fixed the issue that the parser for CIM-XML received from the WBEM server accepted characters for char16 typed values outside of the range for UCS-2 characters. Such characters are now rejected by raising ParseError.
Fixed the issue that the parser for CIM-XML received from the WBEM server tolerated invalid child elements under INSTANCE, ERROR and PROPERTY.REFERENCE elements, and invalid attributes on the PROPERTY.ARRAY element. This now results in a ParseError being raised.
Fixed the issue that the parser for CIM-XML received from the WBEM server did not set the propagated attribute to False in CIMProperty objects retrieved from operations (e.g. as part of a class or instance), as required by DSP0201. It does now.
Fixed the issue that VALUE.NULL (for representing array items that are NULL) was not supported in array values returned by the WBEM server. Note that it already had been supported for array values sent to the server, or in CIM-XML created by toximcml() methods (Issue #1022).
Fixed the issue that the size of a fixed-size array property declaration was ignored when retrieving classes from CIM operations. It is now represented in the array_size attribute of the returned CIMProperty objects. (Issue #1031).
Fixed the issue that the xml:lang attributes that are allowed on some CIM-XML elements have been rejected by raising ParseError. They are now tolerated but ignored (Issue #1033).
Fixed the issue that mixed case values (e.g. “True”) for the boolean attributes of the QUALIFIER element in CIM-XML was not supported and resulted in ParseError to be raised (Issue #1042).
Fixed the issue that an empty boolean value in a CIM-XML response returned from a WBEM server was accepted and treated as a NULL value. This treatment does not conform to DSP0201. Empty boolean values now cause a UserWarning to be issued, but otherwise continue to work as before. (Issue #1032).
Fixed the issue that invalid values were accepted for the boolean attributes of the SCOPE element in CIM-XML received from a WBEM server. They now cause ParseError to be raised (Issue #1040).
Fixed the issue that invalid values for the boolean attributes of QUALIFIER.DECLARATION elements in CIM-XML responses from WBEM servers were tolerated and treated as False. They now cause ParseError to be raised (Issue #1041).
Fixed the incorrect default value for the propagated constructor parameter of CIMMethod. Previously, the default value was False and it has been corrected to be None, consistent with its meaning of “information not available”. The only CIM operations that take a CIMMethod object as input are CreateClass() and ModifyClass() (as part of the class that is created or modified). Because WBEM servers must ignore the propagated information on any elements in the provided class, this change is backwards compatible for the CIM operations. (Issue #1039).
Added support for setting the propagated attribute on CIMQualifier objects returned from CIM operations to a default of False when it is not specified in the CIM-XML response, consistent with DSP0201, and consistent with how it was already done for other CIM objects. This change should normally be backwards compatible for pywbem users, because they don’t even know whether the information has been set by the server or defaulted by the client as it is now done. (Issue #1039).
Added support for setting the flavor attributes on CIMQualifier and CIMQUalifierDeclaration objects returned from CIM operations to their default values defined in CIM-XML, when they are not specified in the CIM-XML response, consistent with DSP0201, and consistent with how it was already done for other CIM objects. This change should normally be backwards compatible for pywbem users, because they don’t even know whether the information has been set by the server or defaulted by the client as it is now done. (Issue #1039).
In the wbemcli shell, fixed the “*params” parameter of the im() function, to become “params” (an iterable). (Issue #1110).
For the InvokeMethod operation, fixed that passing Python None as an input parameter valus resulted in TypeError. Extended the testclient testcases for InvokeMethod accordingly. Documented that None is a valid CIM typed value (Issue #1123).
Fixed the error that embedded instances in parameter values were incorrectly represented with the CIM-XML element corresponding to their path (e.g. VALUE.NAMEDINSTANCE). The path is now correctly ignored on embedded instance parameter values, and they are always represented as INSTANCE elements (Issue #1136).
Fixed the error that CIMInstance.tocimxml()/tocimxmlstr() represented its instance path always with a VALUE.NAMEDINSTANCE element and generated incorrect child elements depending which components of the instance path were present. Now, the element for the path depends correctly on the components that are present in the instance path (Issue #1136).
Fixed the missing support for generating a VALUE.INSTANCEWITHPATH element in CIM-XML. This is needed when a CIMInstance with path has namespace and host. This error was previously now showing up because the VALUE.NAMEDINSTANCE element was always created (Issue #1136).
Fixed the error that the tocimxml() and tocimxmlstr() methods of CIMProperty, CIMQualifier and CIMQualifierDeclaration represented NULL entries in array values using an empty VALUE element. They now correctly generate the VALUE.NULL element for NULL entries (Issue #1136). In order to provide for backwards compatibility to WBEM servers that do not support VALUE.NULL, a config option SEND_VALUE_NULL was added that by default sends VALUE.NULL, but allows for disabling that (Issue #1144).
Fixed the error that the special float values INF, -INF and NaN were represented in lower case in CIM-XML. DSP0201 requires the exact case INF, -INF and NaN (Issue #1136).
Fixed the error that float values in CIM-XML were truncated to six significant digits. They now have at least the minimum number of significant digits required by DSP0201: 11 for real32, and 17 for real64. (Issue #1136).
In the WBEMServer.get_central_instances() method, fixed the error that a CIM status code of CIM_ERR_METHOD_NOT_FOUND returned when attempting to invoke the GetCentralInstances() CIM method lead to failing the get_central_instances() method. Now, execution continues with attempting the next approach for determining the central instances (Issue #1145).
In the mof_compiler.bat script file, fixed the issue that it did not return an exit code if the MOF compiler failed (Issue #1156).
Several fixes and display related improvements in the mof_compiler script: MOF file not found is now also handled instead of failing with an exception traceback. Exceptions are now displayed before exiting. Dry-run mode is now displayed, for information. The target MOF repository is now always displayed; previously it was displayed only in verbose mode. (Issue #1157).
Cleanup:
- Removed the unimplemented and unused popitem() method of NocaseDict.
- The atomic_to_cim_xml() function and any generated CIM-XML now generates boolean values in upper case ‘TRUE’ and ‘FALSE’, following the recommendation in DSP0201. Previously, boolean values were produced in lower case. This change is compatible for WBEM servers that meet the requirement of DSP0201 to treat boolean values case-insensitively.
- Cleaned up the implementation of CIMProperty/CIMParameter.tocimxml(), so that it is now easier understandable (as part of fixing issue #1136).
- Removed any logging.NullHandler objects on pywbem loggers, including the pywbem listener loggers, because it turns out that for the use of loggers as a trace tool, the DEBUG level is used by the pywbem client and the INFO level is used by the pywbem listener, which are both not printed by default by the Python root logger, so the use of null handlers is not really needed (Issue #1175).
Build, test, quality:
Added a boolean config variable DEBUG_WARNING_ORIGIN that when enabled causes a stack traceback to be added to the message of most warnings issued by pywbem. This allows identifying which code originated the warning.
Cleaned up a lot of pylint warnings, for things like missing-doc, etc. so that we can actually review the remainder. See issue #808.
Update to current DMTF Schema (2.49.0) for pywbem tests. This also validates that pywbem can compile this DMTF released schema. See issue #816
Add unit tests for the iter… operations. See issue #818
Migrated installation and development setup to use pbr and Pip requirements files. As a consequence, removed files no longer used: os_setup.py, uninstall_pbr_on_py26.py.
Added ability to test with minimum Python package level, according to the package versions defined in minimum-constraints.txt.
Fixed a setup issue on Travis CI with duplicate metadata directories for the setuptools package. This issue prevented downgrading setuptools for the test with minimum package levels. Added script remove_duplicate_setuptools.py for that.
Reorganized the make targets for installing pywbem and its dependencies somewhat. They now need to be used in this order:
- make install - installs pywbem and dependencies for runtime
- make develop - installs dependencies for development
There are two new targets (that are included in the targets above, when first run after a make clobber):
- make install_os - installs OS-level dependencies for runtime
- make develop_os - installs OS-level dependencies for development
Enabled testing on OS-X in the Travis CI.
Added unit test for WBEMServer class using pywbem_mock. See the file testsuite/test_wbemserverclass.py. This test is incomplete today but tests most of the main paths.
Documentation:
Improved the complete pywbem documentation (Issue #1115). Some specific changes are listed in the remainder of this section.
- The installation for Windows on Python 2.7 now requires an additional manual step for installing the M2CryptoWin32/64 Python package. For details, see the Installation section in the documentation.
- Fixed the documentation of the CIMInstanceName.keybindings setter method, by adding ‘number’ as an allowed input type.
- Moved the detail documentation of input to child element lists (e.g. for properties of CIMInstance) as a data type ‘properties input object’, etc., into the glossary. These types are now referenced as the type of the corresponding parameter.
- Clarified that the return type of BaseOperationRecorder.open_file() is a file-like object and that the caller is responsible for closing that file.
- Clarified in the description of the return_type init parameter of CIMMethod that array return types, void return types, and reference return types are all not supported in pywbem. See issue #1038, for void.
- Fixed the type string for the keys of the CIMInstance.qualifiers attribute to be unicode string.
- Many clarifications for CIM objects, e.g. about case preservation of CIM element names, or making copies of input parameters vs. storing the provided object.
- Improved the description of the WBEMConnection.ModifyInstance() method.
- Improved the description of the tocimxml() and tocimxmlstr() methods on CIM objects.
- Clarifications and small fixes in the documentation of the WBEMConnection.Iter…() generator functions.
- Added “New in pywbem M.N …” text to descriptions of anything that was introduced in pywbem 0.8.0 or later.
- Clarified use of ca_certs parameter of WBEMConnection and its defaults in DEFAULT_CA_CERT_PATHS.
- Clarified that the instance path returned by the CreateInstance() operation method has classname, keybindings and namespace set.
- For CIM floating point types (real32, real64), added cautionary text for equality comparison and hash value calculation.
- Clarified that CIM-XML multi-requests are not supported by pywbem and why that is not a functional limitation.
- In the wbemcli shell, improved and fixed the description of operation functions (Issue #1110).
- Improved and fixed the description of WBEMConnection operation methods (Issue #1110).
- Improved and fixed the description of the pywbem statistics support (Issue #1115).
- Clarified the use of logging for the pywbem client (in section 4.8 “WBEM operation logging”) and for the pywbem listener (in section 6.1.2 “Logging in the listener” (Issue #1175).
pywbem 0.11.0¶
Released: 2017-09-27
This version contains all fixes up to pywbem 0.10.1.
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.
Added the MOF compiler API to the
pywbem
namespace. For compatibility, it is still available in thepywbem.mof_compiler
namespace. See issue #634.Modify the pattern used for cim_operation.py request methods from using except/else to use except/finally to reduce number of places code like the recorder call and future statistics, log, etc. calls have to be included. No other functional changes. See issue #680
Add operation statistics gathering experimental. Adds the class Statistics which serves as a common place to gather execution time and request/reply size information on server requests and replies. The detailed information is available in WBEMConnection for operation execution time and request/reply content size at the end of each operation.
When statistics gathering is enabled, the information is placed into the Statistics class where min/max/avg information is available for each operation type. Statistics gathering is enabled if the WBEMConnection attribute enable_stats is True.
Statistics can be externalized through the snapshot method of the Statistics class.
The functionality is marked experimental for the current release
See issue #761
Extended development.rst to define how to update dmtf mof and move thevariables for this process from test_compiler.py to a separate file to make them easy to find. See issue #54
Changed CIMInstancename.__repr__() to show the key bindings in the iteration order, and no longer in sorted order, to better debug iteration order related issues. See issue #585.
Add new notebooks to the tutorials including notebooks for the WBEMServer class, the pull operations, and the Iter operations. See issue #682
Added unit test for recorder. See issue #676
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.
Extend the documentation to list support for specific non-specification features of some WBEM servers. Issue #653.
Extend cim_http.py, cim_operations.py, _statistics.py to handle optional WBEMServerResponseTime header from WBEMServer. This HTTP header reports the server time in microseconds from request to response in the operation response. The extension adds the WBEMConnection property last_server_response_time and places the time from the server into the attribute for this property.
Extend pywbem to handle optional WBEMServerResponseTime header from a WBEM server. This HTTP header reports the server time in microseconds from request to response in the operation response. The extension adds the WBEMConnection property last_server_response_time and places the time from the server into the attribute for this property. It also passes server_response_time to statistics so that max/min/avg are maintained. See issue # 687.
Add test for wbemcli script that will execute the script and test results. issue #569
Experimental: Add logging to record information passing between the pywbem client and WBEM servers both for the WBEMConnection methods that drive information interchange and the http requests and responses. Logging includes a new module (_logging.py) that provides configuration of logging. The logging extends WBEMConnection with methods so that the user can chose to log a)Calls and returns from the WBEMConnection methods that interact with the WBEMServer (ex. getClass), b)http request/responses, c)both. The logging uses the python logging package and the output can be directed to either stderr or a file. The user can chose to log the complete requests and responses or size limited subsets (log_detail level). See issue #691.
Clarify documentation on wbem operation recorder in client.rst. see issue #741
Added an optional class path to the CIMClass class, as a convenience for the user in order so that CIMClass objects are self-contained w.r.t. their path. The class path is set in CIMClass objects returned by the GetClass, EmumerateClasses, and the class-level Associators and References operations. The path is added purely on the client side, based on existing information returned from WBEM server. This change does therefore not affect the interactions with WBEM servers at all. issue #349.
Added a
host
property toWBEMConnection
which contains the host:port component of the WBEM server’s URL. This helps addressing issue #349.Made sure that
repr()
on CIM objects produces a reliable order of items such as properties, qualifiers, methods, parameters, scopes, by ordering them by their names. This makes debugging usingrepr()
easier for pywbem users, and it also helps in some unit test cases of pywbem itself.Made sure that
str()
onCIMInstanceName
produces reliable order of key bindings in the returned WBEM URI, by ordering them by key name.
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.
- Add constructor parameter checking to QualifierDeclaration. See issue #645.
- 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 issue in mof_compiler where instance aliases were incomplete. They only included the class component so that if they were used in the definition of other instances (ex. to define an association where a reference property was the aliased instance, the reference path was incomplete.) This is now a path with keybindings. Note: It is the responsibility of the user to make these instances complete (i.e. with all key properties) see issue #679
- Correct documentation issue in cim_obj (Exceptions definition missing). See issue #677
- Add more mock tests. ModifyInstance was missing and some others were missing an error test. issue#61
- add –version option to mof_compiler and pywbem cli tools. Generates the pywbem version string. See issue # 630
- Fix several issues in recorder including issue #609:indent by 4, # 676: invalid yaml representation for namedtuples that result from open/pull operations, #700 and #663: recorder won’t write utf8 (at least for our tests), #698 : datetime test failures because of timezone, Most of these are tested with the new test_recorder.py unit test.
- Fix error in wbemcli with –enable_stats arg. Since this was added in this release, the bug was never public. See issue #709
- Remove extra print in cim_operations. See issue # 704
- Correct Error in run_cimoperations with use of namespace in iter… function See issue #718. This was a test code issue. No changes to the iter operations.
- Correct issue with Recorder creating non-text files. This issue Documents the requirement for text files and also adds a static method to force creation of the recorder output as a text file. See issue # 700
- Correct issue in wbemcli.bat where it was not returning error level. see issue #727
- Correct issue where dependency pip installs end up with old version of coverage package. This old version generates unwanted deprecation messages that are fixed after version 4.03. This requires a change to the travis.yaml file directly to force a reinstall of coverage. See issue #734
- Fixed the issue that
CIMProperty.__init__()
had an incorrect check for thereference_class
parameter, where it checked the class name specified in that parameter to be the creation class of the referenced instance. According to DSP0201, reference_class is the declared class, which can be a superclass of the creation class of the referenced instance. This is related to issue #598 - Modify mof_compiler documentation to indication issues with property names that are compiler keywords. See issue #62.
- Correct issue where dependency pip installs end up with old version of coverage package. This old version generates unwanted deprecation messages that are fixed after version 4.03. This requires a change to the travis.yaml file directly to force a reinstall of coverage. See issue #734
- Fix minor doc issue in client.rst. See issue #740.
- 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.
- Clean up pylint new messages tied to use of len and if else. See issue #770
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).
- Added a testcase for CIMInstanceName to compare two objects with different ordering of their key bindings for equality. See issue #686.
- In
parse_property_reference()
intupleparse.py
, a number of attributes of the newCIMProperty
object had been updated after having created it. That bypasses the checks in its__init__()
method. This has been improved to pass these values in when creating the object. - 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). - Improved the build process to ensure that half-built artefacts are removed before building (issue #754).
- 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.
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.
- Added material to README and changed to use restructured text. issue #642
pywbem 0.10.0¶
Released: 2016-12-20
Incompatible changes:
- All methods of the WBEMSubscriptionManager class that returned instance paths (or lists thereof) in pywbem 0.9.x 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 pywbem 0.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 0.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 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 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 pywbem 0.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 0.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 0.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 0.8.2¶
Released: 2016-03-20
Bug fixes:
- Eliminated dependency on six package during installation of pywbem. (Andreas Maier)
Dependencies:
- Pywbem 0.8.x has the following dependencies on other PyPI packages
(see install_requires argument in setup script):
- M2Crypto
- ply
- six
pywbem 0.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 pywbem 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 pywbem 0.7.0, the module was at the same time the script. (Andreas Maier)
- In pywbem 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 pywbem 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 0.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 (https://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 0.6¶
Released: 2007-10-26 (not on Pypi)
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 0.5¶
Released: 2006-11-21 (not on Pypi)
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 0.4¶
Released: 2005-11-15 (not on Pypi)
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)