Pywbem - A WBEM client¶
Pywbem is a WBEM client, written in pure Python. It supports Python 2 and Python 3.
A WBEM client allows issuing operations to a WBEM server, using the CIM operations over HTTP (CIM-XML) protocol defined in the DMTF standards DSP0200 and DSP0201. The CIM/WBEM infrastructure is used for a wide variety of systems management tasks supported by systems running WBEM servers. See WBEM Standards for more information about WBEM.
This package is based on the idea that a good WBEM client should be easy to use and not necessarily require a large amount of programming knowledge. It is suitable for a large range of tasks from simply poking around to writing web and GUI applications.
The general pywbem web site is: http://pywbem.github.io/pywbem/index.html.
Introduction¶
Functionality¶
Pywbem supports the following functionality:
-
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 creates, updates or removes CIM instances, classes or qualifier types in a CIM repository.
See DSP0004 for a description of MOF (Managed Object Format).
By default, the CIM repository used by the MOF compiler is in a WBEM server. The MOF compiler API provides for plugging in your own CIM repository the compiler can work against.
-
A WBEM command line interface that provides an interactive Python environment for issuing WBEM operations to a WBEM server.
-
Installation¶
Pywbem is a pure Python package that can be installed from PyPi or from its repository by the usual means for installing Python packages.
Some of the Python packages used by pywbem have dependencies on operating
system packages. As of pywbem v0.8, the setup script has support for installing
prerequisite operating system packages via a new install_os
command for the
setup script. Alternatively, you can establish these prerequisites yourself.
For details, see Prerequisite operating system packages.
The following examples show different ways to install pywbem. They all ensure that prerequisite Python packages are installed as needed:
Install the latest released version, assuming the OS-level prerequisites are already established:
$ pip install pywbem
Install the latest released version and also install (or display) any OS-level prerequisites:
$ pip download --no-deps --no-binary :all: pywbem $ tar -xzf pywbem-*.tar.gz
or, when using
pip
versions before 8.0.0, you have to know the pywbem version to download:$ curl -L https://github.com/pywbem/pywbem/archive/v0.9.0.tar.gz |tar -xz
Followed in both cases by these commands:
$ cd pywbem-* $ python setup.py install_os install
Install a particular branch from the Git repository:
$ pip install git+https://github.com/pywbem/pywbem.git@<branch-name>
These examples install pywbem and its prerequisite Python packages into the currently active Python environment. By default, the system Python environment is active. This is probably the right choice if you just want to use the scripts that come with pywbem. In that case, you need to prepend the installation commands shown above (i.e. pip and python setup.py) with sudo, and your Linux userid needs to be authorized accordingly. If your intention is to write code against the pywbem APIs, installation into a virtual Python environment is recommended).
The second example installs the OS-level prerequisites always into the system, regardless of whether or not you have a virtual Python environment active. The setup script uses sudo under the covers. This means that you don’t need to take care about that and can use sudo to control whether you install the Python packages into a virtual or system Python environment.
The command syntax above is shown for Linux, but works in similar ways on Windows and OS-X.
In case of trouble with the installation, see the Troubleshooting section.
You can verify that pywbem and its dependent packages are installed correctly by importing the package into Python:
$ python -c "import pywbem; print('ok')"
ok
Prerequisite operating system packages¶
Prerequisite operating system packages can be installed by the pywbem setup
script using a new command install_os
:
$ python setup.py install_os
For a number of well-known Linux distributions, the setup script will install
the packages using the respective installer program (e.g. yum
on RHEL). For
other Linux distributions and for non-Linux operating systems, the setup script
will display the package names that would be needed on RHEL, leaving it to the
user to translate them accordingly.
When installing such packages on Linux, the setup script uses the sudo
command, so your userid needs to be authorized accordingly.
This command also downbloads and builds swig
and installs its build
prerequisites if it cannot be installed as an operating system package in the
required version.
The second example in the previous section shows how to use the new setup
command install_os
. It is really simple to be used and avoids the manual
procedure for establishing the operating system packages as described in the
remainder of this section.
For manual installation of the prerequisite operating system packages, or for including pywbem in distributions, the following table lists the packages and their version requirements for a number of Linux distributions:
Distributions | Package name | Version requirements |
---|---|---|
RedHat, CentOS, Fedora | openssl-devel | >=1.0.1 |
gcc-c++ | >=4.4 | |
python-devel | for Python 2.6, 2.7 | |
python3{N}u-devel | for Python 3.{N} from IUS community (python3{N}u) | |
python3{N}-devel | for Python 3.{N} not from IUS (python3{N}) | |
swig | >=2.0 | |
Ubuntu, Debian, LinuxMint | libssl-dev | >=1.0.1 |
g++ | >=4.4 | |
python-dev | for Python 2.6, 2.7 | |
python3-dev | for Python 3.4 - 3.6 | |
swig | >=2.0 | |
SLES, OpenSUSE | openssl-devel | >=1.0.1 |
gcc-c++ | >=4.4 | |
python-devel | for Python 2.6, 2.7 | |
python3-devel | for Python 3.4 - 3.6 | |
swig | >=2.0 |
On some distributions, the swig
package is not available in the required
version. In such cases, it can be built from its sources, as follows:
Install the
pcre-devel
package (RedHat etc. and SLES etc.) or thelibpcre3
andlibpcre3-dev
packages (Ubuntu etc.).Download the swig source archive and unpack it:
$ wget -q -O swig-2.0.12.tar.gz http://sourceforge.net/projects/swig/files/swig/swig-2.0.12/swig-2.0.12.tar.gz/download $ tar -xf swig-2.0.12.tar.gz
Configure and build it:
$ cd swig-2.0.12 $ ./configure --prefix=/usr $ make swig
Install it:
$ sudo make install
Verify its version:
$ swig -version SWIG Version 2.0.12
Package version¶
The version of the pywbem package can be accessed by programs using the
pywbem.__version__
variable:
-
pywbem._version.
__version__
= '0.10.1'¶ Version of the pywbem package, as a string.
Possible formats for the version string are:
- “M.N.U.dev0”: During development of future M.N.U release (not released to PyPI)
- “M.N.U.rcX”: Release candidate X of future M.N.U release (not released to PyPI)
- “M.N.U”: The final M.N.U release
Note: For tooling reasons, the variable is shown as
pywbem._version.__version__
, but it should be used as
pywbem.__version__
.
Supported environments¶
Pywbem is supported in these environments:
- Operating Systems: Linux, Windows, OS-X
- Python: 2.6, 2.7, 3.4, 3.5, 3.6
Limitations:
- On Windows, pywbem is not supported on Python 2.6, because M2Crypto in the M2CryptoWin32/64 package does not support Python 2.6.
- On Windows, pywbem has not been tested on 64-bit versions of Python, because the libxslt etc. development packages needed to install lxml that are used do not provide the link libraries in the format needed by lxml. Because lxml is only used for development and test of pywbem, just running pywbem on 64-bit versions of Windows may or may not work.
Standards conformance¶
Pywbem conforms to the following CIM and WBEM standards, in the version specified when following the links to the standards:
The supported WBEM protocol is CIM-XML; it conforms to DSP0200 and DSP0201.
The CIM-XML representation of CIM objects as produced by their
tocimxml()
andtocimxmlstr()
methods conforms to DSP0201.The MOF as produced by the
tomof()
methods on CIM objects and as parsed by the MOF compiler conforms to DSP0004.Limitations:
- Several issues in the MOF compiler.
The implemented CIM metamodel (e.g. in the CIM objects) conforms to DSP0004.
The WBEM URIs produced by the
pywbem.CIMInstanceName.__str__()
andpywbem.CIMClassName.__str__()
methods conform to DSP0207.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 conforms to DSP1033.
The mechanisms for subscribing for CIM indications in the WBEM indication API conforms to DSP1054.
Deprecation policy¶
Since its v0.7.0, Pywbem attempts to be as backwards compatible as possible.
However, in an attempt to clean up some of its history, and in order to prepare for future additions, the Python namespaces visible to users of pywbem need to be cleaned up.
Also, occasionally functionality needs to be retired, because it is flawed and a better but incompatible replacement has emerged.
In pywbem, such changes are done by deprecating existing functionality, without removing it. The deprecated functionality is still supported throughout new minor releases. Eventually, a new major release will break compatibility and will remove the deprecated functionality.
In order to prepare users of pywbem for that, deprecation of functionality is
stated in the API documentation, and is made visible at runtime by issuing
Python warnings of type DeprecationWarning
(see the Python
warnings
module).
Since Python 2.7, DeprecationWarning
messages are suppressed by default.
They can be shown for example in any of these ways:
- By specifying the Python command line option:
-W default
- By invoking Python with the environment variable:
PYTHONWARNINGS=default
It is recommended that users of the pywbem package run their test code with
DeprecationWarning
messages being shown, so they become aware of any use of
deprecated functionality.
Here is a summary of the deprecation and compatibility policy used by pywbem, by release type:
- New update release (M.N.U -> M.N.U+1): No new deprecations; fully backwards compatible.
- New minor release (M.N.U -> M.N+1.0): New deprecations may be added; as backwards compatible as possible.
- New major release (M.N.U -> M+1.0.0): Deprecated functionality may get removed; backwards compatibility may be broken.
Compatibility is always seen from the perspective of the user of pywbem, so a backwards compatible new pywbem release means that the user can safely upgrade to that new release without encountering compatibility issues.
Python namespaces¶
The external APIs of pywbem are defined by the symbols in the pywbem
namespace. With a few exceptions, that is the only Python namespace that needs
to be imported by users.
With pywbem versions prior to v0.8, it was common for users to import the
sub-modules of pywbem (e.g. pywbem.cim_obj
). The sub-modules that existed
prior to v0.8 are still available for compatibility reasons.
Starting with v0.8, the pywbem
namespace was cleaned up, and not all public
symbols available in the sub-module namespaces are available in the pywbem
namespace anymore. The symbols in the sub-module namespaces are still available
for compatibility, including those that are no longer available in the
pywbem
namespace. However, any use of symbols from the sub-module namespaces
is deprecated starting with v0.8, and you should assume that a future version of
pywbem will remove them. If you miss any symbol you were used to use, please
open an issue.
New sub-modules added since pywbem v0.8 have a leading underscore in their name in order to document that they are considered an implementation detail and that they should not be imported by users.
The only exception to the single-namespace rule stated above, is the
MOF compiler API, which uses the pywbem.mof_compiler
namespace.
This documentation describes only the external APIs of pywbem, and omits any internal symbols and any sub-modules.
Configuration variables¶
Pywbem supports a very limited number of configuration variables that influence certain specific behavior.
These configuration variables are read by pywbem only after its modules have been loaded, so they can be modified by the user directly after importing pywbem. For example:
import pywbem
pywbem.ENFORCE_INTEGER_RANGE = False
Note that the pywbem source file defining these variables should not be changed by the user. Instead, the technique shown in the example above should be used to modify the configuration variables.
Note: Due to limitations of the documentatin tooling, the following
configuration variables are shown in the pywbem.config
namespace. However,
they should be used from the pywbem
namespace.
-
pywbem.config.
ENFORCE_INTEGER_RANGE
= True¶ Enforce the allowable value range for CIM integer types (e.g.
Uint8
). For details, see 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.
- 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 as IterEnumerateInstance this value will be used as the value for MaxObjectCount. Note that this does not necessarily optimize the performance of these operations.
Tutorial¶
This section contains a few short tutorials about using pywbem. It is intended to be enough to get people up and going who already know a bit about WBEM and CIM.
The tutorials in this section are Jupyter Notebooks, and are shown using the online Jupyter Notebook Viewer. This allows viewing the tutorials without having Jupyter Notebook installed locally.
In order to view a tutorial, just click on a link in this table:
Tutorial | Short description |
---|---|
connections.ipynb | Making connections to a WBEM server |
datamodel.ipynb | Representation of CIM objects in Python |
enuminsts.ipynb | EnumerateInstances |
enuminstnames.ipynb | EnumerateInstanceNames |
getinstance.ipynb | GetInstance |
createdeleteinst.ipynb | CreateInstance + DeleteInstance |
modifyinstance.ipynb | ModifyInstance |
invokemethod.ipynb | InvokeMethod |
subscriptionmanager.ipynb | Subscription Manager |
For the following topics, tutorials are not yet available:
- Pulled Enumerations
- ExecQuery
- Association Operations
- Class Operations
- Qualifier Operations
- WBEMServer
- WBEMListener
- WBEMSubscriptionManager
Executing code in the tutorials¶
You cannot directly modify or execute the code in the tutorials using the Jupyter Notebook Viewer, though. In order to do that, the Jupyter Notebook Viewer provides a download button at the top right corner of the page.
You must have Jupyter Notebook installed, preferrably in a virtual Python environment, and you must have pywbem installed.
To see a list of your downloaded notebook files, start Jupyter Notebook as follows:
jupyter notebook --notebook-dir={your-notebook-dir}
WBEM client library API¶
The WBEM client library API supports issuing WBEM operations to a WBEM server, using the CIM operations over HTTP (CIM-XML) protocol defined in the DMTF standards DSP0200 and DSP0201.
This chapter has the following sections:
- WBEM operations - Class
WBEMConnection
is the main class of the WBEM client library API and is used to issue WBEM operations to a WBEM server. - CIM objects - Python classes for representing CIM objects (instances, classes, properties, etc.) that are used by the WBEM operations as input or output.
- CIM data types - Python classes for representing values of CIM data types.
- CIM status codes - CIM status codes returned by failing WBEM operations.
- Exceptions - Exceptions specific to pywbem that may be raised.
- Security considerations - Information about authentication types and certificates.
A number of these topics apply also to the other APIs of the pywbem package.
WBEM operations¶
Objects of the WBEMConnection
class represent a connection to
a WBEM server.
All WBEM operations defined in DSP0200 can be issued across this connection.
Each method of this class corresponds directly to a WBEM operation.
WBEMConnection method | Purpose |
---|---|
EnumerateInstanceNames() |
Enumerate the instance paths of instances of a class (including instances of its subclasses). |
EnumerateInstances() |
Enumerate the instances of a class (including instances of its subclasses) |
GetInstance() |
Retrieve an instance |
ModifyInstance() |
Modify the property values of an instance |
CreateInstance() |
Create an instance |
DeleteInstance() |
Delete an instance |
AssociatorNames() |
Retrieve the instance paths of the instances (or classes) associated to a source instance (or source class) |
Associators() |
Retrieve the instances (or classes) associated to a source instance (or source class) |
ReferenceNames() |
Retrieve the instance paths of the association instances (or association classes) that reference a source instance (or source class) |
References() |
Retrieve the association instances (or association classes) that reference a source instance (or source class) |
InvokeMethod() |
Invoke a method on a target instance or on a target class |
ExecQuery() |
Execute a query in a namespace |
IterEnumerateInstances() |
Experimental: Iterator API that uses either OpenEnumerateInstances and PullInstancesWithPath or EnumerateInstances depending on the attributes and existence of pull operations in the server. |
IterEnumerateInstancePaths() |
Experimental: Iterator API that uses either OpenEnumerateInstances and PullInstancesWithPath or EnumerateInstances depending on the attributes and existence of pull operations in the server. |
IterReferenceInstances() |
Experimental: Iterator API that uses either OpenReferenceInstances and PullInstancesWithPath or References depending on the attributes and existence of pull operations in the server. |
IterReferenceInstancePaths() |
Experimental: Iterator API that uses either OpenReferenceInstances and PullInstancesWithPath or References depending on the attributes and existence of pull operations in the server. |
IterAssociatorInstances() |
Experimental: Iterator API that uses either OpenAssociatorInstances and PullInstancesWithPath or Associators depending on the attributes and existence of pull operations in the server. |
IterAssociatorInstancePaths() |
Experimental: Iterator API that uses either OpenAssociatorInstances and PullInstancesWithPath or Associators depending on the attributes and existence of pull operations in the server. |
IterQueryInstances() |
Experimental: Iterator API that uses either OpenQueryInstances and PullInstances or ExecQuery depending on the attributes and existence of pull operations in the server. |
OpenEnumerateInstances() |
Open enumeration session to retrieve instances of of a class (including instances of its subclass) |
OpenAssociatorInstances() |
Open enumeration session to retrieve the instances associated to a source instance |
OpenReferenceInstances() |
Open enumeration session to retrieve the instances that reference a source instance |
PullInstancesWithPath() |
Continue enumeration session opened with OpenEnumerateInstances, OpenAssociatorInstances, or OpenReferenceinstances |
OpenEnumerateInstancePaths() |
Open enumeration session to retrieve instances of a class (including instances of its subclass) |
OpenAssociatorInstancePaths() |
Open enumeration session to retrieve the instances associated to a source instance |
OpenReferenceInstancePaths() |
Open enumeration session to retrieve the instances that reference a source instance |
PullInstancePaths() |
Continue enumeration session opened with OpenEnumerateInstancePaths, OpenAssociatorInstancePaths, or OpenReferenceInstancePaths |
OpenQueryInstances() |
Open query request to retrieve instances defined by the query parameter in a namespace |
PullInstances() |
Continue enumeration of enumeration session opened with OpenExecQuery |
CloseEnumeration() |
Close an enumeration session in process. |
EnumerateClassNames() |
Enumerate the names of subclasses of a class, or of the top-level classes in a namespace |
EnumerateClasses() |
Enumerate the subclasses of a class, or the top-level classes in a namespace |
GetClass() |
Retrieve a class |
ModifyClass() |
Modify a class |
CreateClass() |
Create a class |
DeleteClass() |
Delete a class |
EnumerateQualifiers() |
Enumerate qualifier declarations |
GetQualifier() |
Retrieve a qualifier declaration |
SetQualifier() |
Create or modify a qualifier declaration |
DeleteQualifier() |
Delete a qualifier declaration |
NOTE: The method EnumerationCount is to be deprecated from the DMTF specs and has not been implemented by any servers so was not implemented in pywbem
WBEMConnection¶
-
class
pywbem.
WBEMConnection
(url, creds=None, default_namespace='root/cimv2', x509=None, verify_callback=None, ca_certs=None, no_verification=False, timeout=None, use_pull_operations=None)[source]¶ A client’s connection to a WBEM server. This is the main class of the WBEM client library API.
The connection object knows a default CIM namespace, which is used when no namespace is specified on subsequent WBEM operations (that support specifying namespaces). Thus, the connection object can be used as a connection to multiple CIM namespaces on a WBEM server (when the namespace is specified on subsequent operations), or as a connection to only the default namespace (this allows omitting the namespace on subsequent operations).
As usual in HTTP, there is no persistent TCP connection; the connectedness provided by this class is only conceptual. That is, the creation of the connection object does not cause any interaction with the WBEM server, and each subsequent WBEM operation performs an independent, state-less HTTP/HTTPS request.
After creating a
WBEMConnection
object, various methods may be called on the object, which cause WBEM operations to be issued to the WBEM server. See WBEM operations for a list of these methods.CIM elements such as instances or classes are represented as Python objects (see CIM objects). The caller does not need to know about the CIM-XML encoding of CIM elements and protocol payload that is used underneath (It should be possible to use a different WBEM protocol below this layer without disturbing any callers).
The connection remembers the XML of the last request and last reply if debugging is turned on via the
debug
attribute of the connection object. This may be useful in debugging: If a problem occurs, you can examine 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.The methods of this class may raise the following exceptions:
Exceptions indicating processing errors:
ConnectionError
- A connection with the WBEM server could not be established or broke down.AuthError
- Authentication failed with the WBEM server.HTTPError
- HTTP error (bad status code) received from WBEM server.ParseError
- The response from the WBEM server cannot be parsed (for example, invalid characters or UTF-8 sequences, ill-formed XML, or invalid CIM-XML).CIMError
- The WBEM server returned an error response with a CIM status code.TimeoutError
- The WBEM server did not respond in time and the client timed out.
Exceptions indicating programming errors:
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.
Variables: - .. – All parameters of the
WBEMConnection
constructor are set as public attribute with the same name. - debug (
bool
) –A boolean indicating whether logging of the last request and last reply is enabled.
The initial value of this attribute is False. Debug logging can be enabled for future operations by setting this attribute to True.
- last_request (unicode string) – CIM-XML data of the last request sent to the WBEM server on this connection, formatted as prettified XML. Prior to sending the very first request on this connection object, it is None.
- last_raw_request (unicode string) – CIM-XML data of the last request sent to the WBEM server on this connection, formatted as it was sent. Prior to sending the very first request on this connection object, it is None.
- last_reply (unicode string) – CIM-XML data of the last response received from the WBEM server on this connection, formatted as prettified XML. Prior to receiving the very first response on this connection object, it is None.
- last_raw_reply (unicode string) – CIM-XML data of the last response received from the WBEM server on this connection, formatted as it was received. Prior to receiving the very first response on this connection object, it is None.
- operation_recorder (
BaseOperationRecorder
) –This attribute provides for recording of the operations that are executed on this connection. Initially, this attribute is None. If None, no operations are recorded. If set to an object of a subclass of
BaseOperationRecorder
, each operation that is executed on this connection will be recorded by invoking itsrecord()
method. All operations except the Iter... operations may be recorded. Since the Iter... operations utilize the other operations to send requests their calls are NOT recorded.All operations except the Iter... operations may be recorded. Since the Iter... operations utilize the other operations to send requests their calls are NOT recorded.
- use_pull_operations (
bool
) –Indicates whether the client will attempt the use of pull operations in any Iter...() methods. However, each operation has its own internal equivalent flag based on this flag to allow for implementations that implement only some of the pull operations. The method set_use_pull_operations may be used to reset all of these flags to a defined value.
This variable is initially set from the same-named input argument. If it is None is modified when Iter...() methods are invoked, dependent on the support for pull operations in the WBEM server. After the first call , the varaible will be either True or False and indicating whether pull operations will be used in this and subsequent Iter...() methods.
Parameters: - url (string) –
URL of the WBEM server, in the format:
[{scheme}://]{host}[:{port}]
The following URL schemes are supported:
https
: Causes HTTPS to be used.http
: Causes HTTP to be used.
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986
with the extensions for zone identifiers as defined in
RFC6874, supporting
-
(minus) for the delimiter before the zone ID string, as an additional choice to%25
.
If no port is specified in the URL, the default ports are:
- If HTTPS is used, port 5989.
- If HTTP is used, port 5988.
Examples for some URL formats:
"https://10.11.12.13:6988"
: Use HTTPS to port 6988 on host 10.11.12.13"https://mysystem.acme.org"
: Use HTTPS to port 5989 on host mysystem.acme.org"10.11.12.13"
: Use HTTP to port 5988 on host 10.11.12.13"http://[2001:db8::1234]:15988"
: Use HTTP to port 15988 on host 2001:db8::1234"http://[::ffff.10.11.12.13]"
: Use HTTP to port 5988 on host ::ffff.10.11.12.13 (an IPv4-mapped IPv6 address)"http://[2001:db8::1234%25eth0]"
or"http://[2001:db8::1234-eth0]"
: Use HTTP to port 5988 to host 2001:db8::1234 (a link-local IPv6 address) using zone identifier eth0
- creds (
tuple
of userid, password) –Credentials for HTTP authenticatiion with the WBEM server, as a tuple(userid, password), with:
- userid (string): Userid for authenticating with the WBEM server.
- password (string): Password for that userid.
If None, the client will not generate
Authorization
headers in the HTTP request. Otherwise, the client will generate anAuthorization
header using HTTP Basic Authentication.See Authentication types for an overview.
- default_namespace (string) –
Name of the CIM namespace to be used by default (if no namespace is specified for an operation).
Default:
DEFAULT_NAMESPACE
. - x509 (
dict
) –X.509 client certificate and key file to be presented to the WBEM server during the TLS/SSL handshake.
This parameter is ignored when HTTP is used.
If None, no client certificate is presented to the server, resulting in 1-way authentication to be used.
Otherwise, the client certificate is presented to the server, resulting in 2-way authentication to be used. This parameter must be a dictionary containing the following two items:
See Authentication types for an overview.
- verify_callback (callable) –
Registers a callback function that will be called to verify the X.509 server certificate returned by the WBEM server during the TLS/SSL handshake, in addition to the validation already performed by the TLS/SSL support.
This parameter is ignored when HTTP is used.
Note that the validation performed by the TLS/SSL support already includes the usual validation, so that normally a callback function does not need to be used. See Verification of the X.509 server certificate for details.
Warning: This parameter is not used when the python environment is Python 3 because the ssl module does not support it.
If None, no such callback function will be registered.
The specified function will be called for the returned certificate, and for each of the certificates in its chain of trust.
See M2Crypto.SSL.Context.set_verify for details, as well as http://blog.san-ss.com.ar/2012/05/validating-ssl-certificate-in-python.html):
The callback function must take five parameters:
- the M2Crypto.SSL.Connection object that triggered the verification.
- an OpenSSL.crypto.X509 object representing the certificate to be validated (the returned certificate or one of the certificates in its chain of trust).
- an integer containing the error number (0 in case no error) of any validation error detected by M2Crypto. You can find their meaning in the OpenSSL documentation.
- an integer indicating the depth (=position) of the certificate to be validated (the one in the second parameter) in the chain of trust of the returned certificate. A value of 0 indicates that the returned certificate is currently validated; any other value indicates the distance of the currently validated certificate to the returned certificate in its chain of trust.
- an integer that indicates whether the validation of the certificate specified in the second parameter passed or did not pass the validation by M2Crypto. A value of 1 indicates a successful validation and 0 an unsuccessful one.
The callback function must return True if the verification passes and False otherwise.
- ca_certs (string) –
Location of CA certificates (trusted certificates) for verifying the X.509 server certificate returned by the WBEM server.
This parameter is ignored when HTTP is used.
The parameter value is either the directory path of a directory prepared using the
c_rehash
tool included with OpenSSL, or the file path of a file in PEM format.If None, default directory paths will be used to look up CA certificates (see
DEFAULT_CA_CERT_PATHS
). - no_verification (
bool
) –Disables verification of the X.509 server certificate returned by the WBEM server during TLS/SSL handshake, and disables the invocation of a verification function specified in verify_callback.
If True, verification is disabled; otherwise, verification is enabled.
This parameter is ignored when HTTP is used.
Disabling the verification of the server certificate is insecure and should be avoided!
- timeout (number) –
Timeout in seconds, for requests sent to the server. If the server did not respond within the timeout duration, the socket for the connection will be closed, causing a
TimeoutError
to be raised.A value of None means that the connection uses the standard timeout behavior of Python sockets, which can be between several minutes and much longer. Because this is somewhat unpredictable, it is recommended to specify a value for the timeout.
A value of
0
means the timeout is very short, and does not really make any sense.Note that not all situations can be handled within this timeout, so for some issues, operations may take longer before raising an exception.
- use_pull_operations (
bool
) –Controls the use of pull operations in any Iter...() methods, by intializing a corresponding instance variable that is used during any Iter...() methods. The default value (None) will work on any WBEM server whether or not it supports pull operations.
None means that the Iter...() methods will attempt a pull operation first, and if the WBEM server does not support it, will use a traditional operation. The corresponding instance variable will be adjusted to indicate what the WBEM server supports.
True means that the Iter...() methods will only use pull operations. If the WBEM server does not support pull operations, a
CIMError
with status code CIM_ERR_NOT_SUPPORTED will be raised.False means that the Iter...() methods will only use traditional operations.
-
__str__
()[source]¶ Return a short representation of the
WBEMConnection
object for human consumption.
-
__repr__
()[source]¶ Return a representation of the
WBEMConnection
object with all attributes (except for the password in the credentials) that is suitable for debugging.
-
imethodcall
(methodname, namespace, response_params_rqd=None, **params)[source]¶ This is a low-level method that is used by the operation-specific methods of this class (e.g.
EnumerateInstanceNames()
). This method is not part of the external WBEM client library API; it is being included in the documentation only for tooling reasons.Deprecated: Calling this function directly has been deprecated and will issue a DeprecationWarning. Users should call the operation-specific methods instead of this method.
-
methodcall
(methodname, localobject, Params=None, **params)[source]¶ This is a low-level method that is used by the
InvokeMethod()
method of this class. This method is not part of the external WBEM client library API; it is being included in the documentation only for tooling reasons.Deprecated: Calling this function directly has been deprecated and will issue a DeprecationWarning. Users should call
InvokeMethod()
instead of this method.
-
EnumerateInstanceNames
(ClassName, namespace=None, **extra)[source]¶ Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.
This method performs the EnumerateInstanceNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as aCIMClassName
object, its host attribute will be ignored. - namespace (string) –
Name of the CIM namespace to be used (case independent).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A list of
CIMInstanceName
objects that are the enumerated instance paths, with its attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: None, indicating the WBEM server is unspecified.
Raises: Exceptions described in
WBEMConnection
.- ClassName (string or
-
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).
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 instance, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property in the returned instances, as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A list of
CIMInstance
objects that are representations of the enumerated instances.The path attribute of each
CIMInstance
object is 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
-
IterEnumerateInstances
(ClassName, namespace=None, LocalOnly=None, DeepInheritance=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple EnumerateInstances/OpenEnumerateInstance methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenEnumerateInstances()
andPullInstancesWithPath()
operations (pull operations) or theEnumerateInstances()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open... function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open... on other pull operation types the first time each type is used.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for EnumerateInstances so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Otherwise, this method raises an exception.
Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as 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).
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 instance, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property in the returned instances, as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Many WBEM servers do not support this request attribute so that its use is NOT recommended except in special cases.
If this attribute is True and the method uses the EnumerateInstances option (use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError
- 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 issues as part of the execution of this generator.
- If positive, the WBEM server is to return no more than the specified number of instances.
- Zero is not allowed; it would mean that zero instances are to be returned for every request issued to the server.
- The default is defined as a system config variable.
- None is not allowed.
The choice of MaxObjectCount is client/server dependent but choices between 100 and 1000 typically do not have a significant impact on either memory or overall efficiency.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.Returns: A Python generator object. Instances can be retrieved by iterating through the object. Instances that are retrieved include the host and namespace component of the instance path.
Example:
insts_iterator = conn.IterEnumerateInstances('CIM_Blah') for inst in insts_iterator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_iterator.close() break else: print('instance %s' % inst.tomof())
-
IterEnumerateInstancePaths
(ClassName, namespace=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple EnumerateInstances/OpenEnumerateInstance methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenEnumerateInstancePaths()
andPullInstancePaths()
operations (pull operations) or theEnumerateInstanceNames()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations are supported for either all or none of the defined Open.... Since the first request determines whether operations continue with the pull operations, if one of the Open... functions is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will decide that None of the operations are supported. Resetting the use_pull_operations to None may be used to override the decision made by the Iter... method for other operations.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for EnumerateInstances so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Otherwise, this method raises an exception.
Parameters: - ClassName (string or
CIMClassName
) – Name of the class to be enumerated (case independent). If specified as 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).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used. - FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. If this attribute is True and the method uses the EnumerateInstances option (either use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Many WBEM servers do not support this request attribute so that its use is NOT recommended except in special cases.
If this attribute is True and the method uses the EnumerateInstances option (use_pull_operations == False or the server does not support pull operations), the method will fail with a ValueError
- 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 instance paths the WBEM server may return for each of the open and pull requests issues as part of the execution of this iterator.
- If positive, the WBEM server is to return no more than the specified number of instance paths.
- Zero is not allowed; it would mean that zero paths are to be returned for every request issued.
- The default is defined as a system config variable.
- None is not allowed.
The choice of MaxObjectCount is client/server dependent but choices between 100 and 1000 typically do not have a significant impact on either memory or overall efficiency.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.Returns: A Python:term:generator object. Instance paths can be retrieved by iterating through the object. In all cases the instance paths are complete including host and namespace information.
Example:
paths_iterator = conn.IterEnumerateInstancePaths('CIM_Blah') for path in paths_iterator: print('path %s' % path)
-
IterReferenceInstancePaths
(InstanceName, ResultClass=None, Role=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve references from a WBEM Server. This method frees the user of choices between the multiple ReferenceNames/ReferenceInstancePaths methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenReferenceInstancePaths operation (see :term:`DSP0200()
) andEnumerateInstances()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open... function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open... on other pull operation types the first time each type is used.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Otherwise, this method raises an exception.
Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - ResultClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation because the act of the server filtering requires that it generate instances and then discard them.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
- Zero is not allowed; it would mean that zero instances are to be returned for every request issued to the server.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises: Exceptions described in
WBEMConnection
.Example:
insts_iterator = conn.IterReferencePaths('CIM_Blah') for inst in insts_iterator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_iterator.close() break else: print('instance %s' % inst.tomof())
-
IterReferenceInstances
(InstanceName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple EnumerateInstances/OpenEnumerateInstance methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenReferenceInstances()
andPullInstancesWithPath()
operations (pull operations) or theReferences()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open... function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open... on other pull operation types the first time each type is used.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - ResultClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instances (or classes), as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string) –
An iterable specifying the names of the properties to be included in the returned instances (or classes) (case independent). An empty iterable indicates to include no properties.
If None, all properties are included.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises: Exceptions described in
WBEMConnection
.Example:
insts_iterator = conn.IterReferenceInstances('CIM_Blah.key=1', ...) for inst in insts_iterator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_iterator.close() break else: print('instance %s' % inst.tomof())
-
IterAssociatorInstancePaths
(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve associators from a WBEM Server. This method frees the user of choices between the multiple AssociatorNames/AssociatorInstancePaths methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenAssociatorInstancePaths operation (see :term:`DSP0200()
) andAssociatorNames()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open... function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open... on other pull operation types the first time each type is used.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Otherwise, this method raises an exception.
Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - AssocClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- ResultClass (string or
CIMClassName
) –Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- ResultRole (string) –
Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.
None means that no such filtering is peformed.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation because the act of the server filtering requires that it generate instances and then discard them.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
- Zero is not allowed; it would mean that zero instances are to be returned for every request issued to the server.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default behaviour to be used. DSP0200 defines that the server-implemented default is to return zero instances.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises: Exceptions described in
WBEMConnection
.Example:
insts_iterator = conn.IterAssociatorInstancePaths('CIM_Blah') for inst in insts_iterator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_iterator.close() break else: print('instance %s' % inst.tomof())
-
IterAssociatorInstances
(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple Associators/OpenAssociatorInstance methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenAssociatorInstances()
andPullInstancesWithPath()
operations (pull operations) or theAssociators()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open... function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open... on other pull operation types the first time each type is used.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for ReferenceNames so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Parameters: - InstanceName (
CIMInstanceName
) –- The instance path of the source instance.
- If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
- AssocClass (string or
CIMClassName
): - Class name of an association class (case independent),
to filter the result to include only traversals of that association
class (or subclasses).
None means that no such filtering is peformed.
- ResultClass (string or
CIMClassName
) –Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- ResultRole (string) –
Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.
None means that no such filtering is peformed.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instances (or classes), as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string) –
An iterable specifying the names of the properties to be included in the returned instances (or classes) (case independent). An empty iterable indicates to include no properties.
If None, all properties are included.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A Python:term:generator object. Instances can be retrieved by iterating through the object.
Raises: Exceptions described in
WBEMConnection
.Example:
insts_iterator = conn.IterAssociatorInstances('CIM_Blah.key=1',...) for inst in insts_iterator: # close if a particular property value found if inst.get('thisPropertyName') == 0 insts_iterator.close() break else: print('instance %s' % inst.tomof())
-
IterQueryInstances
(FilterQueryLanguage, FilterQuery, namespace=None, ReturnQueryResultClass=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=1000, **extra)[source]¶ A generator function to retrieve instances from a WBEM Server. This method frees the user of choices between the multiple ExecQuery/OpenQueryInstances methods and reduces the enumeration to a pythonic iterator idiom.
Experimental: This method is experimental in this release.
This method performs either the
OpenQueryInstances()
andPullInstances()
operations (pull operations) or theExecQuery()
operation (traditional operation) if the WBEM server does not support the pull operations. It is an alternative to using these operations directly, that automatically uses the pull operations if supported.The use_pull_operations argument of the
WBEMConnection
constructor can be used to override that default behavior to either force the use of pull operations or to avoid their use.NOTE: This functionality assumes that pull operations may not be supported for all of the pull operation types (i.e. operations whose name starts with Open). Even if one Open... function is not implemented (returns CIM_ERR_NOT_SUPPORTED) and that operation is used as the first request, the code will try the Open... on other pull operation types the first time each type is used.
This method provides all of the controls of the pull operations API except the ability to set the response size on each request; response size (defined by MaxObjectCount is the same for all of the request operations in the sequence). There are, limitations in that:
- The filter function does not exist for EnumerateInstances so that a request with FilterQuery or FilterQueryLanguage attribute will be rejected if the pull operatons do not exist on the target WBEM Server.
- If ContinueOnError is set and the pull operations are not supported on the server, the request is rejected.
An open request may be closed while the iteration process is being executed by issuing the iterator close() method.
If the initial request of the operation sequence succeeds, this method returns a Python iterator object so that the instances that are returned from the server can be retrieved with iterator expressions.
Otherwise, this method raises an exception.
Parameters: - QueryLanguage (string) – Name of the query language used in the Query parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. “DMTF:FQL” is not a valid query language for this request.
- Query (string) – Query string in the query language specified in the QueryLanguage parameter.
- namespace (string) –
Name of the CIM namespace to be used (case independent).
If None, the default namespace of the connection object will be used.
- ReturnQueryResultClass (
bool
) – Controls whether a class definition is returned. - OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A Python:term:generator object. Instances can be retrieved by iterating through the object. An Instance of the nexted class IterQueryInstancesReturn that contains two properties:
query_result_class: If a result class was requested from by the call to InterQueryInstances and one was returned, the CIMClass representing this class is returned. Otherwise, None is returned
generator: That defines a generator for the instances returned from whichever lower level function is called. The instances are accessed using this generator (ex. for inst in rtn.generator:)
Raises: Exceptions described in
WBEMConnection
.Example
- result = conn.IterQueryInstances(‘DMTF:CQL’,
- ‘SELECT FROM * where pl > 2’)
- for inst in result.generator:
- print(‘instance %s’ % inst.tomof())
Raises: Exceptions described in WBEMConnection
.
-
OpenEnumerateInstancePaths
(ClassName, namespace=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]¶ Open an enumeration session to enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.
This method performs the OpenEnumerateInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns status on the enumeration session and optionally instance paths. Otherwise, this method raises an exception.
Use
PullInstancePaths()
request to retrieve the next set of instance paths or theCloseEnumeration()
request to close the enumeration session early.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).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used. - FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation (i.e. return the CIM_ERR_NOT_SUPPORTED exception when filtering is specified) because the act of the server filtering requires that it generate instances and then discard them.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:paths (
list
ofCIMInstanceName
): Representations of the initial set of enumerated instance paths, with their attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- ClassName (string or
-
OpenEnumerateInstances
(ClassName, namespace=None, LocalOnly=None, DeepInheritance=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]¶ Open an enumeration session to get instances of a class (including instances of its subclasses).
This method performs the OpenEnumerateInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.
Use
PullInstances()
request to retrieve the next set of instance paths or theCloseEnumeration()
request to close the enumeration session early.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).
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 instance, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property in the returned instances, as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string) –
An iterable specifying the names of the properties to be included in the returned instances (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:instances (
list
ofCIMInstance
): Representations of the initial set of 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: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- ClassName (string or
-
OpenReferenceInstancePaths
(InstanceName, ResultClass=None, Role=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]¶ Open an enumeration session to retrieve the instance paths of the association instances that reference a source instance.
This method does not support retrieving classes.
This method performs the OpenReferenceInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instance paths. Otherwise, this method raises an exception.
Use
PullInstances()
request to retrieve the next set of instance paths or theCloseEnumeration()
request to close the enumeration session early.Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - ResultClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation because the act of the server filtering requires that it generate instances and then discard them.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:paths (
list
ofCIMInstanceName
): Representations of the initial set of enumerated instance paths, with their attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- 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.
This method does not support retrieving classes.
This method performs the OpenReferenceInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.
Use
PullInstances()
request to retrieve the next set of instance paths or theCloseEnumeration()
request to close the enumeration session early.Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - ResultClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instances (or classes), as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:instances (
list
ofCIMInstance
): Representations of the initial set of 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: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- 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.
This method does not support retrieving classes.
This method performs the OpenAssociatorInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instance paths. Otherwise, this method raises an exception.
Use
PullInstancePaths()
request to retrieve the next set of instance paths or theCloseEnumeration()
request to close the enumeration session early.Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - AssocClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- ResultClass (string or
CIMClassName
) –Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- ResultRole (string) –
Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.
None means that no such filtering is peformed.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter. Not all WBEM servers allow FilterQuery filtering for this operation (i.e. return the CIM_ERR_NOT_SUPPORTED exception when filtering is specified) because the act of the server filtering requires that it generate instances and then discard them.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:paths (
list
ofCIMInstanceName
): Representations of the initial set of enumerated instance paths, with their attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- InstanceName (
-
OpenAssociatorInstances
(InstanceName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, FilterQueryLanguage=None, FilterQuery=None, OperationTimeout=None, ContinueOnError=None, MaxObjectCount=None, **extra)[source]¶ Open an enumeration session to retrieve the instances associated to a source instance.
This method does not support retrieving classes.
This method performs the OpenAssociatorInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.
The subsequent operation after this open is successful and result.eos = False must be either the
PullInstances()
request or theCloseEnumeration()
request.Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the source instance. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - AssocClass (string or
CIMClassName
) –Class name of an association class (case independent), to filter the result to include only traversals of that association class (or subclasses).
None means that no such filtering is peformed.
- ResultClass (string or
CIMClassName
) –Class name of an associated class (case independent), to filter the result to include only traversals to that associated class (or subclasses).
None means that no such filtering is peformed.
- Role (string) –
Role name (= property name) of the source end (case independent), to filter the result to include only traversals from that source role.
None means that no such filtering is peformed.
- ResultRole (string) –
Role name (= property name) of the far end (case independent), to filter the result to include only traversals to that far role.
None means that no such filtering is peformed.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instances (or classes), as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
- FilterQueryLanguage (string) – A string defining the name of the query language used for the FilterQuery parameter. The DMTF defined language (FQL) (DSP0212) is specified as ‘DMTF:FQL’.
- FilterQuery (string) – A string defining the query that is to be sent to the WBEM server using the query language defined by the FilterQueryLanguage parameter.
- OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:instances (
list
ofCIMInstance
): Representations of the initial set of 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: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- 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.
This method performs the OpenQueryInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally CIM instances representing the query result. Otherwise, this method raises an exception.
The subsequent operation after this open is successful and result.eos is False, must be either the
PullInstances()
request or theCloseEnumeration()
request.Parameters: - FilterQueryLanguage (string) – Name of the query language used in the Query parameter, e.g. “DMTF:CQL” for CIM Query Language, and “WQL” for WBEM Query Language. “DMTF:FQL” is not a valid query language for this request.
- FilterQuery (string) – Query string in the query language specified in the QueryLanguage parameter.
- namespace (string) –
Name of the CIM namespace to be used (case independent).
If None, the default namespace of the connection object will be used.
- ReturnQueryResultClass (
bool
) – Controls whether a class definition is returned. - OperationTimeout (
Uint32
) –Minimum time in seconds the WBEM Server shall maintain an open enumeration session after a previous Open or Pull request is sent to the client. Once this timeout time has expired, the WBEM server may close the enumeration session.
- If not None, this parameter is sent to the WBEM server as the
proposed timeout for the enumeration session. A value of 0
indicates that the server is expected to never time out. The
server may reject the proposed value, causing a
CIMError
to be raised with status 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:instances (
list
ofCIMInstance
): Representations of the initial set of enumerated instances.The path attribute of each
CIMInstance
object is None, because query results are not addressable CIM instances.eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: The inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
query_result_class (
CIMClass
): If the ReturnQueryResultClass parameter is True, this tuple item contains a class definition that defines the properties of each row (instance) of the query result. Otherwise, None.
Raises: Exceptions described in
WBEMConnection
.
-
PullInstancesWithPath
(context, MaxObjectCount, **extra)[source]¶ Retrieve the next set of instances with path from an open enumeraton session defined by the enumeration_context parameter. The retrieved instances include their instance paths.
This method performs the PullInstancesWithPath operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.
Parameters: - context (string) –
Identifies the enumeration session, including its current enumeration state. This must be the value of the context item in the
namedtuple
object returned from the previous open or pull operation for this enumeration.The tuple items are:
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server shall return for this request. This parameter is required for each Pull request.
- If positive, the WBEM server is to return no more than the specified number of instances.
- If zero, the WBEM server is to return no instances. This may be used by a client to reset the interoperation timer
- None is not allowed for this operation.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:instances (
list
ofCIMInstance
): Representations of the next set of 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: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- context (string) –
-
PullInstancePaths
(context, MaxObjectCount, **extra)[source]¶ Retrieve the next set of instance paths from an open enumeraton session defined by the enumeration_context parameter.
This method performs the PullInstancePaths operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instance paths. Otherwise, this method raises an exception.
Parameters: - context (string) –
Identifies the enumeration session, including its current enumeration state. This must be the value of the context item in the
namedtuple
object returned from the previous open or pull operation for this enumeration.The tuple items are:
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server shall return for this request. This parameter is required for each Pull request.
- If positive, the WBEM server is to return no more than the specified number of instances.
- If zero, the WBEM server is to return no instances. This may be used by a client to reset the interoperation timer.
- None is not allowed for this operation.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:paths (
list of
CIMInstanceName
): Representations of the next set of enumerated instance paths, with their attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace.
eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- context (string) –
-
PullInstances
(context, MaxObjectCount, **extra)[source]¶ Retrieve the next set of instances from an open enumeraton session defined by the enumeration_context parameter.
This method performs the PullInstances operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns enumeration session status and optionally instances. Otherwise, this method raises an exception.
Parameters: - context (string) –
Identifies the enumeration session, including its current enumeration state. This must be the value of the context item in the
namedtuple
object returned from the previous open or pull operation for this enumeration.The tuple items are:
- MaxObjectCount (
Uint32
) –Maximum number of instances the WBEM server shall return for this request. This parameter is required for each Pull request.
- If positive, the WBEM server is to return no more than the specified number of instances.
- If zero, the WBEM server is to return no instances. This may be used by a client to reset the interoperation timer.
- None is not allowed for this operation.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
namedtuple
object containing the following named items:instances (
list
ofCIMInstance
): Representations of the next set of enumerated instances.The path attribute of each
CIMInstance
object is None, because this operation does not return instance paths.eos (
bool
): Indicates whether the enumeration session is exhausted after returning the initial set of enumerated instances.- If True, the enumeration session is exhausted, and the server has closed the enumeration session.
- If False, the enumeration session is not exhausted.
context (
tuple
of server_context, namespace): Identifies the opened enumeration session. The client must provide this value for subsequent operations on this enumeration session.The tuple items are:
- server_context (string): Enumeration context string returned by the server if the session is not exhausted, or None otherwise. This string is opaque for the client.
- namespace (string): Name of the CIM namespace that was used for this operation.
NOTE: This inner tuple hides the need for a CIM namespace on subsequent operations in the enumeration session. CIM operations always require target namespace, but it never makes sense to specify a different one in subsequent operations on the same enumeration session.
Raises: Exceptions described in
WBEMConnection
.- context (string) –
-
CloseEnumeration
(context, **extra)[source]¶ The CloseEnumeration closes an open enumeration session, performing an early termination of an incomplete enumeration session.
This method performs the CloseEnumeration operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
This method should not used if the enumeration session has terminated and will result in an exception response.
If the operation succeeds, this method returns. Otherwise, it raises an exception.
Parameters: ( (context) – term: string) The enumeration_context paramater must contain the Context value returned by the WBEM server with the response to the previous open or pull operation for this enumeration sequence. Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation. Raises: Exceptions described in WBEMConnection
.
-
GetInstance
(InstanceName, LocalOnly=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]¶ Retrieve an instance.
This method performs the GetInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - InstanceName (
CIMInstanceName
) – The instance path of the instance to be retrieved. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - LocalOnly (
bool
) –Controls the exclusion of inherited properties from the returned instance, as follows:
- If False, inherited properties are not excluded.
- If True, inherited properties are basically excluded, but the behavior may be WBEM server specific.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.
This parameter has been deprecated in DSP0200 and should be set to False by the caller.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned instance, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property in the returned instance, as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instance (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
CIMInstance
object that is a representation of the retrieved instance. Its path attribute is 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.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ModifiedInstance (
CIMInstance
) –A representation of the modified instance, also indicating its instance path.
The path attribute of this object identifies the instance to be modified. Its keybindings attribute is required. If its namespace attribute is None, the default namespace of the connection will be used. Its host attribute will be ignored.
The classname attribute of the instance path and the classname attribute of the instance must specify the same class name.
The properties defined in this object specify the new property values for the instance to be modified. Missing properties (relative to the class declaration) and properties provided with a value of None will be set to NULL.
Typically, this object has been retrieved by other operations, such as
GetInstance()
. - IncludeQualifiers (
bool
) –Indicates that qualifiers are to be modified as specified in the ModifiedInstance parameter, as follows:
- If False, qualifiers not modified.
- If True, qualifiers are modified if the WBEM server implements support for this parameter.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.
This parameter has been deprecated in DSP0200. Clients cannot rely on it being implemented by WBEM servers.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be modified (case independent).
An empty iterable indicates to modify no properties.
If None, all properties are modified.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.- ModifiedInstance (
-
CreateInstance
(NewInstance, namespace=None, **extra)[source]¶ Create an instance in a namespace.
This method performs the CreateInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
The creation class for the new instance is taken from the classname attribute of the NewInstance parameter.
The namespace for the new instance is taken from these sources, in decreasing order of priority:
- namespace parameter of this method, if not None,
- namespace in path attribute of the NewInstance parameter, if not None,
- default namespace of the connection.
Parameters: - NewInstance (
CIMInstance
) –A representation of the CIM instance to be created.
The classname attribute of this object specifies the creation class for the new instance.
Apart from utilizing its namespace, the path attribute is ignored.
The properties attribute of this object specifies initial property values for the new CIM instance.
Instance-level qualifiers have been deprecated in CIM, so any qualifier values specified using the qualifiers attribute of this object will be ignored.
- namespace (string) – Name of the CIM namespace to be used (case independent).
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
CIMInstanceName
object that is the instance path of the new instance.Raises: Exceptions described in
WBEMConnection
.
-
DeleteInstance
(InstanceName, **extra)[source]¶ Delete an instance.
This method performs the DeleteInstance operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: InstanceName ( CIMInstanceName
) – The instance path of the instance to be deleted. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation. Raises: Exceptions described in WBEMConnection
.
-
AssociatorNames
(ObjectName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, **extra)[source]¶ Retrieve the instance paths of the instances associated to a source instance.
Retrieve the class paths of the classes associated to a source class.
This method performs the AssociatorNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ObjectName –
The object path of the source object, as follows:
- For instance-level usage: The instance path of the source
instance, as a
CIMInstanceName
object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - For class-level usage: The class path of the source class, as a
string or
CIMClassName
object:If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).
If specified as a
CIMClassName
object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.
- For instance-level usage: 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: The returned list of objects depend on the usage:
- For instance-level usage: A list of
CIMInstanceName
objects that are the instance paths of the associated instances, with their attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- For class-level usage: A list of
CIMClassName
objects that are the class paths of the associated classes, with their attributes set as follows:- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
Raises: Exceptions described in
WBEMConnection
.- ObjectName –
-
Associators
(ObjectName, AssocClass=None, ResultClass=None, Role=None, ResultRole=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]¶ Retrieve the instances associated to a source instance.
Retrieve the classes associated to a source class.
This method performs the Associators operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ObjectName –
The object path of the source object, as follows:
- For instance-level usage: The instance path of the source
instance, as a
CIMInstanceName
object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - For class-level usage: The class path of the source class, as a
string or
CIMClassName
object:If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).
If specified as a
CIMClassName
object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.
- For instance-level usage: 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 it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (or classes) (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: The returned list of objects depend on the usage:
For instance-level usage: A list of
CIMInstance
objects that are representations of the associated instances.The path attribute of each
CIMInstance
object is 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 usage: A list of
tuple
of (classpath, class) objects that are representations of the associated classes.Each tuple represents one class and has these items:
- classpath (
CIMClassName
): The class path of the class, with its attributes set as follows:- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- class (
CIMClass
): The representation of the class.
- 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.
Retrieve the class paths of the association classes that reference a source class.
This method performs the ReferenceNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ObjectName –
The object path of the source object, as follows:
- For instance-level usage: The instance path of the source
instance, as a
CIMInstanceName
object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - For class-level usage: The class path of the source class, as a
string or
CIMClassName
object:If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).
If specified as a
CIMClassName
object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.
- For instance-level usage: 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.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: The returned list of objects depend on the usage:
- For instance-level usage: A list of
CIMInstanceName
objects that are the instance paths of the referencing association instances, with their attributes set as follows:- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- For class-level usage: A list of
CIMClassName
objects that are the class paths of the referencing association classes, with their attributes set as follows:- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
Raises: Exceptions described in
WBEMConnection
.- ObjectName –
-
References
(ObjectName, ResultClass=None, Role=None, IncludeQualifiers=None, IncludeClassOrigin=None, PropertyList=None, **extra)[source]¶ Retrieve the association instances that reference a source instance.
Retrieve the association classes that reference a source class.
This method performs the References operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ObjectName –
The object path of the source object, as follows:
- For instance-level usage: The instance path of the source
instance, as a
CIMInstanceName
object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - For class-level usage: The class path of the source class, as a
string or
CIMClassName
object:If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).
If specified as a
CIMClassName
object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.
- For instance-level usage: 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 it being implemented by WBEM servers.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property or method in the returned instances (or classes), as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned instances (or classes) (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: The returned list of objects depend on the usage:
For instance-level usage: A list of
CIMInstance
objects that are representations of the referencing association instances.The path attribute of each
CIMInstance
object is 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 usage: A list of
tuple
of (classpath, class) objects that are representations of the referencing association classes.Each tuple represents one class and has these items:
- classpath (
CIMClassName
): The class path of the class, with its attributes set as follows:- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- class (
CIMClass
): The representation of the class.
- classpath (
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 its order), followed by the set of keyword parameters (in any order). There is no checking for duplicate parameter names.
Parameters: - MethodName (string) – Name of the method to be invoked (case independent).
- ObjectName –
The object path of the target object, as follows:
- For instance-level usage: The instance path of the target
instance, as a
CIMInstanceName
object. If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored. - For class-level usage: The class path of the target class, as a
string or
CIMClassName
object:If specified as a string, the string is interpreted as a class name in the default namespace of the connection (case independent).
If specified as a
CIMClassName
object, its host attribute will be ignored. If this object does not specify a namespace, the default namespace of the connection is used.
- For instance-level usage: The instance path of the target
instance, as a
- Params (iterable of tuples of name,value) –
An iterable of input parameters for the CIM method.
Each iterated item represents a single input parameter for the CIM method and must be a
tuple(name, value)
, with these tuple items:- name (string): Parameter name (case independent)
- value (CIM data type): Parameter value
- :keyword : Each keyword parameter represents a single input parameter 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).
If None, the default namespace of the connection object will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A list of
CIMInstance
objects that represents the query result.These instances have their path attribute set to identify their creation class and the target namespace of the query, but they are not addressable instances.
Raises: Exceptions described in
WBEMConnection
.
-
EnumerateClassNames
(namespace=None, ClassName=None, DeepInheritance=None, **extra)[source]¶ Enumerate the names of subclasses of a class, or of the top-level classes in a namespace.
This method performs the EnumerateClassNames operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - namespace (string) –
Name of the namespace in which the class names are to be enumerated (case independent).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used. - ClassName (string or
CIMClassName
) –Name of the class whose subclasses are to be retrieved (case independent). If specified as a
CIMClassName
object, its host attribute will be ignored.If None, the top-level classes in the namespace will be retrieved.
- DeepInheritance (
bool
) –Indicates that all (direct and indirect) subclasses of the specified class or of the top-level classes are to be included in the result, as follows:
- If False, only direct subclasses of the specified class or only top-level classes are included in the result.
- If True, all direct and indirect subclasses of the specified class or the top-level classes and all of their direct and indirect subclasses are included in the result.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
Note, the semantics of the DeepInheritance parameter in
EnumerateInstances()
is different.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A list of unicode string objects that are the class names of the enumerated classes.
Raises: Exceptions described in
WBEMConnection
.- namespace (string) –
-
EnumerateClasses
(namespace=None, ClassName=None, DeepInheritance=None, LocalOnly=None, IncludeQualifiers=None, IncludeClassOrigin=None, **extra)[source]¶ Enumerate the subclasses of a class, or the top-level classes in a namespace.
This method performs the EnumerateClasses operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - namespace (string) –
Name of the namespace in which the classes are to be enumerated (case independent).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used. - ClassName (string or
CIMClassName
) –Name of the class whose subclasses are to be retrieved (case independent). If specified as a
CIMClassName
object, its host attribute will be ignored.If None, the top-level classes in the namespace will be retrieved.
- DeepInheritance (
bool
) –Indicates that all (direct and indirect) subclasses of the specified class or of the top-level classes are to be included in the result, as follows:
- If False, only direct subclasses of the specified class or only top-level classes are included in the result.
- If True, all direct and indirect subclasses of the specified class or the top-level classes and all of their direct and indirect subclasses are included in the result.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
Note, the semantics of the DeepInheritance parameter in
EnumerateInstances()
is different. - LocalOnly (
bool
) –Indicates that inherited properties, methods, and qualifiers are to be excluded from the returned classes, as follows.
- If False, inherited elements are not excluded.
- If True, inherited elements are excluded.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned classes, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property and method in the returned classes, as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A list of
CIMClass
objects that are representations of the enumerated classes.Raises: Exceptions described in
WBEMConnection
.- 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).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used. - LocalOnly (
bool
) –Indicates that inherited properties, methods, and qualifiers are to be excluded from the returned class, as follows.
- If False, inherited elements are not excluded.
- If True, inherited elements are excluded.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is True.
- IncludeQualifiers (
bool
) –Indicates that qualifiers are to be included in the returned class, as follows:
- If False, qualifiers are not included.
- If True, qualifiers are included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- IncludeClassOrigin (
bool
) –Indicates that class origin information is to be included on each property and method in the returned class, as follows:
- If False, class origin information is not included.
- If True, class origin information is included.
- If None, this parameter is not passed to the WBEM server, and causes the server-implemented default to be used. DSP0200 defines that the server-implemented default is False.
- PropertyList (iterable of string or string) –
An iterable specifying the names of the properties (or a string that defines a single property) to be included in the returned class (case independent).
An empty iterable indicates to include no properties.
If None, all properties are included.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
CIMClass
object that is a representation of the retrieved class.Raises: Exceptions described in
WBEMConnection
.- ClassName (string or
-
ModifyClass
(ModifiedClass, namespace=None, **extra)[source]¶ Modify a class in a namespace.
This method performs the ModifyClass operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - ModifiedClass (
CIMClass
) –A representation of the modified class.
The properties, methods and qualifiers defined in this object specify what is to be modified.
Typically, this object has been retrieved by other operations, such as
GetClass()
. - namespace (string) –
Name of the namespace in which the class is to be modified (case independent).
If None, the default namespace of the connection object will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.- 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).
If None, the default namespace of the connection object will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.- 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).
If None, the namespace of the ClassName parameter will be used, if specified as a
CIMClassName
object. If that is also None, the default namespace of the connection will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.- ClassName (string or
-
EnumerateQualifiers
(namespace=None, **extra)[source]¶ Enumerate qualifier declarations in a namespace.
This method performs the EnumerateQualifiers operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: namespace (string) – Name of the namespace in which the qualifier declarations are to be enumerated (case independent).
If None, the default namespace of the connection object will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation. Returns: A list of CIMQualifierDeclaration
objects that are representations of the enumerated qualifier declarations.Raises: Exceptions described in WBEMConnection
.
-
GetQualifier
(QualifierName, namespace=None, **extra)[source]¶ Retrieve a qualifier declaration in a namespace.
This method performs the GetQualifier operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Returns: A
CIMQualifierDeclaration
object that is a representation of the retrieved qualifier declaration.Raises: Exceptions described in
WBEMConnection
.
-
SetQualifier
(QualifierDeclaration, namespace=None, **extra)[source]¶ Create or modify a qualifier declaration in a namespace.
This method performs the SetQualifier operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: - QualifierDeclaration (
CIMQualifierDeclaration
) – Representation of the qualifier declaration to be created or modified. - namespace (string) –
Name of the namespace in which the qualifier declaration is to be created or modified (case independent).
If None, the default namespace of the connection object will be used.
Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.- QualifierDeclaration (
-
DeleteQualifier
(QualifierName, namespace=None, **extra)[source]¶ Delete a qualifier declaration in a namespace.
This method performs the DeleteQualifier operation (see DSP0200). See WBEM operations for a list of all methods performing such operations.
If the operation succeeds, this method returns. Otherwise, this method raises an exception.
Parameters: Keyword Arguments: extra – Additional keyword arguments are passed as additional operation parameters to the WBEM server. Note that DSP0200 does not define any additional parameters for this operation.
Raises: Exceptions described in
WBEMConnection
.
Operation recording¶
The WBEM client library API provides the possibility to record the WBEM
operations that are executed on a connection. This is disabled by default
and can be enabled by setting the
operation_recorder
instance variable of the
WBEMConnection
object to an operation recorder object,
i.e. to an object of a subclass of BaseOperationRecorder
.
Typical usage scenarios for operation recorders are the tracing of WBEM operations, or the generation of test cases.
Users can write their own operation recorder classes based upon the
abstract base class BaseOperationRecorder
.
The WBEM client library API provides the following operation recorder classes:
Class | Purpose |
---|---|
TestClientRecorder |
Generate test cases for the test_client unit test module. |
-
class
pywbem.
BaseOperationRecorder
[source]¶ Abstract base class defining the interface to an operation recorder, that records the WBEM operations executed in a connection to a WBEM server.
An operation recorder can be registered by setting the
operation_recorder
instance attribute of theWBEMConnection
object to an object of a subclass of this base class.When an operation recorder is registered on a connection, each operation that is executed on the connection will cause the
record()
method of the operation recorder object to be called, if the recorder is enabled.The operation recorder is by default enabled, and can be disabled and re-enabled using the
disable()
andenable()
methods, respectively. This can be used to temporarily pause the recorder.-
enabled
¶ Indicate whether the recorder is enabled.
-
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, with the following named fields and attributes:Variables: - method (unicode string) – Name of the
WBEMConnection
method. - args (
dict
) – Dictionary of input arguments (both positional and keyword-based).
Create new instance of OpArgs_tuple(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, with the following named fields and attributes:Variables: - ret (
object
) –Return value, if the method returned. None, if the method raised an exception.
Note that None may be a legitimate return value, so the test for exceptions should be done based upon the
exc
variable. - exc (
Exception
) – Exception object, if the method raised an exception. None, if the method returned.
Create new instance of OpResult_tuple(ret, exc)
- ret (
-
class
pywbem.
HttpRequest
[source]¶ A named tuple representing the HTTP request sent by the WBEM client, with the following named fields and attributes:
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 HttpRequest_tuple(version, url, target, method, headers, payload)
-
class
pywbem.
HttpResponse
[source]¶ A named tuple representing the HTTP response received by the WBEM client, with the following named fields and attributes:
Variables: - version (number) – HTTP version from the response line (10 for HTTP/1.0, 11 for HTTP/1.1).
- status (number) – HTTP status code from the response line (e.g. 200).
- reason (unicode string) – HTTP reason phrase from the response line (e.g. “OK”).
- headers (
dict
) –A dictionary of all HTTP header fields:
- 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 HttpResponse_tuple(version, status, reason, headers, payload)
-
class
pywbem.
TestClientRecorder
(fp)[source]¶ An operation recorder that generates test cases for each recorded operation. The test cases are in the YAML format suitable for the test_client unit test module of the pywbem project.
Parameters:
- fp (file):
- An open file that each test case will be written to.
-
record
(pywbem_args, pywbem_result, http_request, http_response)[source]¶ Function that records the invocation of a single
WBEMConnection
method, by appending a corresponding test case to the file.Parameters: See
pywbem.BaseOperationRecorder.record()
.
CIM objects¶
CIM objects are local representations of CIM instances, classes, properties, etc., as Python objects. They are used as input to and output from WBEM operations:
CIM object | Purpose |
---|---|
CIMInstanceName |
Instance path of a CIM instance |
CIMInstance |
CIM instance |
CIMClassName |
Name of a CIM class, optionally with class path |
CIMClass |
CIM class |
CIMProperty |
CIM property, both as property value in a CIM instance and as property declaration in a CIM class |
CIMMethod |
CIM method declaration in a CIM class |
CIMParameter |
CIM parameter in a CIM method declaration in a CIM class |
CIMQualifier |
CIM qualifier value |
CIMQualifierDeclaration |
CIM qualifier type/declaration |
NocaseDict¶
NocaseDict
is a dictionary implementation with
case-insensitive but case-preserving keys. It is used for sets of named
CIM elements (e.g. CIM properties in an instance or class, or CIM parameters
in a method).
Except for the case-insensitivity of its keys, it behaves like the built-in
dict
. Therefore, NocaseDict
is not described
in detail in this documentation.
Deprecated: In v0.9.0, support for comparing two NocaseDict instances with the
>
, >
, <=
, >=
operators has been deprecated.
CIMInstanceName¶
-
class
pywbem.
CIMInstanceName
(classname, keybindings=None, host=None, namespace=None)[source]¶ A CIM instance path (aka instance name).
A CIM instance path references a CIM instance in a namespace in a WBEM server. Namespace and WBEM server may be unspecified.
This object can be used like a dictionary of the keybindings of the instance path, with the names of the keybindings (= key properties) as dictionary keys, and their property values as dictionary values.
Variables: - classname (unicode string) –
Name of the creation class of the referenced instance.
This variable will never be None.
- keybindings (NocaseDict) –
Keybindings of the instance path (the key property values of the referenced instance).
Each dictionary item specifies one key property value, with:
- key (string): Key property name
- value (CIM data type): Key property value
This variable will never be None.
- namespace (unicode string) –
Name of the CIM namespace containing the referenced instance.
None means that the namespace is unspecified.
- host (unicode string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced instance, in the format:
host[:port]
The host can be specified in any of the usual formats:
If no port is specified, the default port depends on the context in which the object is used.
None means that the WBEM server is unspecified.
Parameters: - classname (string) –
Name of the creation class of the referenced instance.
Must not be None.
- keybindings (
dict
or NocaseDict) –Keybindings for the instance path (the key property values of the referenced instance).
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
- host (string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced instance.
For details about the string format, see the corresponding instance variable.
None means that the WBEM server is unspecified.
- namespace (string) –
Name of the CIM namespace containing the referenced instance.
None means that the namespace is unspecified.
-
__str__
()[source]¶ Return the untyped WBEM URI of the CIM instance path represented by the
CIMInstanceName
object.The returned WBEM URI is consistent with DSP0207.
-
__repr__
()[source]¶ Return a string representation of the
CIMInstanceName
object that is suitable for debugging.
-
copy
()[source]¶ Return a copy of the
CIMInstanceName
object.
-
update
(*args, **kwargs)[source]¶ Add the positional arguments and keyword arguments to the keybindings, updating the values of those that already exist.
-
has_key
(key)[source]¶ Return a boolean indicating whether the instance path has a keybinding with name key.
-
get
(key, default=None)[source]¶ Return the value of the keybinding with name key, or a default value if a keybinding with that name does not exist.
-
items
()[source]¶ Return a copied list of the keybindings, where each item is a tuple of its keybinding name (in the original lexical case) and its value.
-
iteritems
()[source]¶ Iterate through the keybindings, where each item is a tuple of the keybinding name (in the original lexical case) and the keybinding value.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMInstanceName
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMInstanceName
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the value, as a unicode string.
- classname (unicode string) –
CIMInstance¶
-
class
pywbem.
CIMInstance
(classname, properties=None, qualifiers=None, path=None, property_list=None)[source]¶ A CIM instance, optionally including its instance path.
This object can be used like a dictionary of its properties, with the names of the properties as dictionary keys, and their values as dictionary values.
Variables: - classname (unicode string) –
Name of the creation class of the instance.
This variable will never be None.
- properties (NocaseDict) –
Properties for the instance.
Each dictionary item specifies one property value, with:
- key (string): Property name
- value (
CIMProperty
): Property value
This variable will never be None.
- qualifiers (NocaseDict) –
Qualifiers for the instance.
Each dictionary item specifies one qualifier value, with:
- key (string): Qualifier name
- value (
CIMQualifier
): Qualifier value
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
This variable will never be None.
- path (CIMInstanceName) –
Instance path of the instance.
None means that the instance path is unspecified.
- property_list (
list
of unicode string) –List of property names for use as a filter by some operations on the instance.
None means that the properties are not filtered.
Parameters: - classname (string) – Name of the creation class of the instance. Must not be None.
- properties (
dict
or NocaseDict) –Properties for the instance.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
- qualifiers (
dict
or NocaseDict) –Qualifiers for the instance.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
- path (CIMInstanceName) –
Instance path for the instance.
None means that the instance path is unspecified.
- property_list (iterable of string) –
List of property names for use as a filter by some operations on the instance.
None means that the properties are not filtered.
-
__str__
()[source]¶ Return a short string representation of the
CIMInstance
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMInstance
object that is suitable for debugging.
-
copy
()[source]¶ Return copy of the
CIMInstance
object.
-
update
(*args, **kwargs)[source]¶ Add the positional arguments and keyword arguments to the properties, updating the values of those that already exist.
-
update_existing
(*args, **kwargs)[source]¶ Update the values of already existing properties from the positional arguments and keyword arguments.
-
has_key
(key)[source]¶ Return a boolean indicating whether the instance has a property with name key.
-
get
(key, default=None)[source]¶ Return the value of the property with name key, or a default value if a property with that name does not exist.
-
items
()[source]¶ Return a copied list of the properties, where each item is a tuple of the property name (in the original lexical case) and the property value.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMInstance
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMInstance
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(indent=0)[source]¶ Return a unicode string that is a MOF fragment with the instance specification represented by the
CIMInstance
object.Parameters: indent (integer) – Number of spaces the initial line of the output is indented.
- classname (unicode string) –
CIMClassName¶
-
class
pywbem.
CIMClassName
(classname, host=None, namespace=None)[source]¶ A CIM class path.
A CIM class path references a CIM class in a namespace in a WBEM server. Namespace and WBEM server may be unspecified.
Variables: - classname (unicode string) –
Name of the referenced class.
This variable will never be None.
- namespace (unicode string) –
Name of the CIM namespace containing the referenced class.
None means that the namespace is unspecified.
- host (unicode string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced class, in the format:
host[:port]
The host can be specified in any of the usual formats:
If no port is specified, the default port depends on the context in which the object is used.
None means that the WBEM server is unspecified.
Parameters: - classname (string) –
Name of the referenced class.
Must not be None.
- host (string) –
Host and optionally port of the WBEM server containing the CIM namespace of the referenced class.
For details about the string format, see the corresponding instance variable.
None means that the WBEM server is unspecified.
- namespace (string) –
Name of the CIM namespace containing the referenced class.
None means that the namespace is unspecified.
-
copy
()[source]¶ Return a copy the
CIMClassName
object.
-
__str__
()[source]¶ Return the untyped WBEM URI of the CIM class path represented by the
CIMClassName
object.The returned WBEM URI is consistent with DSP0207.
-
__repr__
()[source]¶ Return a string representation of the
CIMClassName
object that is suitable for debugging.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMClassName
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMClassName
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
- classname (unicode string) –
CIMClass¶
-
class
pywbem.
CIMClass
(classname, properties=None, methods=None, superclass=None, qualifiers=None)[source]¶ A CIM class.
Variables: - classname (unicode string) –
Name of the class.
This variable will never be None.
- superclass (unicode string) –
Name of the superclass of the class.
None means that the class is a top-level class.
- properties (NocaseDict) –
Property declarations of the class.
Each dictionary item specifies one property declaration, with:
- key (string): Property name
- value (
CIMProperty
): Property declaration
This variable will never be None.
- methods (NocaseDict) –
Method declarations of the class.
Each dictionary item specifies one method declaration, with:
This variable will never be None.
- qualifiers (NocaseDict) –
Qualifier values of the class.
Each dictionary item specifies one qualifier value, with:
- key (string): Qualifier name
- value (
CIMQualifier
): Qualifier value
This variable will never be None.
Parameters: - classname (string) –
Name for the class.
Must not be None.
- properties (
dict
or NocaseDict) –Property declarations for the class.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
- methods (
dict
or NocaseDict) –Method declarations for the class.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
- superclass (string) –
Name of the superclass for the class.
If None, the class will be a top-level class.
- qualifiers (
dict
or NocaseDict) –Qualifier values for the class.
For details about the dictionary items, see the corresponding attribute.
If None, the class will have no qualifiers.
-
__str__
()[source]¶ Return a short string representation of the
CIMClass
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMClass
object that is suitable for debugging.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMClass
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMClass
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
()[source]¶ Return a unicode string that is a MOF fragment with the class definition represented by the
CIMClass
object.
- classname (unicode string) –
CIMProperty¶
-
class
pywbem.
CIMProperty
(name, value, type=None, class_origin=None, array_size=None, propagated=None, is_array=None, reference_class=None, qualifiers=None, embedded_object=None)[source]¶ A CIM property.
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.
Variables: - name (unicode string) –
Name of the property.
This variable will never be None.
- value (CIM data type) –
Value of the property (interpreted as actual value when representing a property value, and as default value for property declarations).
None means that the value is Null.
For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string in the constructor.
- type (unicode string) –
Name of the CIM data type of the property (e.g.
"uint8"
).This variable will never be None.
- reference_class (unicode string) –
The name of the referenced class, for reference properties.
None, for non-reference properties.
- embedded_object (unicode string) –
A string value indicating the kind of embedded object represented by the property value.
The following values are defined for this parameter:
"instance"
: The property is declared with 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.
- is_array (
bool
) –A boolean indicating whether the property is an array (True) or a scalar (False).
This variable will never be None.
- array_size (integer) –
The size of the array property, for fixed-size arrays.
None means that the array property has variable size, or that it is not an array.
- class_origin (unicode string) –
The CIM class origin of the property (the name of the most derived class that defines or overrides the property in the class hierarchy of the class owning the property).
None means that class origin information is not available.
- propagated (
bool
) –If not None, indicates whether the property declaration has been propagated from a superclass to this class, or the property value has been propagated from the creation class to this instance (the latter is not really used).
None means that propagation information is not available.
- qualifiers (NocaseDict) –
Qualifier values for the property declaration.
Each dictionary item specifies one qualifier value, with:
- key (string): Qualifier name
- value (
CIMQualifier
): Qualifier value
This variable will never be None.
The constructor infers optional parameters that are not specified (for example, it infers type from the Python type of value and other information). If the specified parameters are inconsistent, an exception is raised. If an optional parameter is needed for some reason, an exception is raised.
Parameters: - name (string) –
Name of the property.
Must not be None.
- value (CIM data type) –
Value of the property (interpreted as actual value when representing a property value, and as default value for property declarations).
None means that the property is Null.
- type (string) –
Name of the CIM data type of the property (e.g.
"uint8"
).None means that the parameter is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.
- class_origin (string) –
The CIM class origin of the property (the name of the most derived class that defines or overrides the property in the class hierarchy of the class owning the property).
None means that class origin information is not available.
- array_size (integer) –
The size of the array property, for fixed-size arrays.
None means that the array property has variable size.
- propagated (
bool
) –If not None, indicates whether the property declaration has been propagated from a superclass to this class, or the property value has been propagated from the creation class to this instance (the latter is not really used).
None means that propagation information is not available.
- is_array (
bool
) –A boolean indicating whether the property is an array (True) or a scalar (False).
None means that the parameter is unspecified, causing the corresponding attribute to be inferred from the value parameter, and if that is None it defaults to False (scalar).
- reference_class (string) –
The name of the referenced class, for reference properties.
None means that the parameter is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.
- qualifiers (
dict
or NocaseDict) –Qualifier values for the property declaration.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
- embedded_object (string) –
A string value indicating the kind of embedded object represented by the property value. Has no meaning for property declarations.
For details about the possible values, see the corresponding attribute.
In addition, None means that the value is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.
Examples:
# a string property: CIMProperty("MyString", "abc") # a uint8 property: CIMProperty("MyNum", 42, "uint8") # a uint8 property: CIMProperty("MyNum", Uint8(42)) # a uint8 array property: CIMProperty("MyNumArray", [1,2,3], "uint8") # a reference property: CIMProperty("MyRef", CIMInstanceName(...)) # an embedded object property containing a class: CIMProperty("MyEmbObj", CIMClass(...)) # an embedded object property containing an instance: CIMProperty("MyEmbObj", CIMInstance(...), embedded_object="object") # an embedded instance property: CIMProperty("MyEmbInst", CIMInstance(...)) # a string property that is Null: CIMProperty("MyString", None, "string") # a uint8 property that is Null: CIMProperty("MyNum", None, "uint8") # a reference property that is Null: CIMProperty("MyRef", None, reference_class="MyClass") # an embedded object property that is Null: CIMProperty("MyEmbObj", None, embedded_object="object") # an embedded instance property that is Null: CIMProperty("MyEmbInst", None, embedded_object="instance")
-
copy
()[source]¶ Return a copy of the
CIMProperty
object.
-
__str__
()[source]¶ Return a short string representation of the
CIMProperty
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMProperty
object that is suitable for debugging.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMProperty
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMProperty
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
CIMMethod¶
-
class
pywbem.
CIMMethod
(name=None, return_type=None, parameters=None, class_origin=None, propagated=False, qualifiers=None, methodname=None)[source]¶ A method declaration in a CIM class.
Variables: - name (unicode string) –
Name of the method.
This variable will never be None.
- return_type (unicode string) –
Name of the CIM data type of the method return type (e.g.
"uint32"
).This variable will never be None. Note that void return types of methods are not supported in CIM.
- class_origin (unicode string) –
The CIM class origin of the method (the name of the most derived class that defines or overrides the method in the class hierarchy of the class owning the method).
None means that class origin information is not available.
- propagated (
bool
) –If not None, indicates whether the method has been propagated from a superclass to this class.
None means that propagation information is not available.
- parameters (NocaseDict) –
Parameter declarations for the method declaration.
Each dictionary item specifies one parameter declaration, with:
- key (string): Parameter name
- value (
CIMParameter
): Parameter declaration
This variable will never be None.
- qualifiers (NocaseDict) –
Qualifier values for the method declaration.
Each dictionary item specifies one qualifier value, with:
- key (string): Qualifier name
- value (
CIMQualifier
): Qualifier value
This variable will never be None.
The constructor stores the input parameters as-is and does not infer unspecified parameters from the others (like
CIMProperty
does).Parameters: - name (string) –
Name of the method (just the method name, without class name or parenthesis).
Must not be None.
Deprecated: This argument has been named methodname before v0.9.0. Using methodname as a named argument still works, but has been deprecated in v0.9.0.
- return_type (string) –
Name of the CIM data type of the method return type (e.g.
"uint32"
).Must not be None
- parameters (
dict
or NocaseDict) –Parameter declarations for the method declaration.
For details about the dictionary items, see the corresponding attribute.
If None, the method will have no parameters, and the dictionary will be empty.
- class_origin (string) –
The CIM class origin of the method (the name of the most derived class that defines or overrides the method in the class hierarchy of the class owning the method).
None means that class origin information is not available.
- propagated (
bool
) –If not None, indicates whether the method has been propagated from a superclass to this class.
None means that propagation information is not available.
- qualifiers (
dict
or NocaseDict) –Qualifier values for the method declaration.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
-
__str__
()[source]¶ Return a short string representation of the
CIMMethod
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMMethod
object that is suitable for debugging.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMMethod
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMMethod
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(indent)[source]¶ Return a unicode string that is a MOF fragment with the method definition represented by the
CIMMethod
object.
- name (unicode string) –
CIMParameter¶
-
class
pywbem.
CIMParameter
(name, type, reference_class=None, is_array=None, array_size=None, qualifiers=None, value=None)[source]¶ A CIM parameter for a method declaration.
Variables: - name (unicode string) –
Name of the parameter.
This variable will never be None.
- type (unicode string) –
Name of the CIM data type of the parameter (e.g.
"uint8"
).This variable will never be None.
- reference_class (unicode string) –
The name of the referenced class, for reference parameters.
None, for non-reference parameters.
- is_array (
bool
) –A boolean indicating whether the parameter is an array (True) or a scalar (False).
This variable will never be None.
- array_size (integer) –
The size of the array parameter, for fixed-size arrays.
None means that the array parameter has variable size, or that it is not an array.
- qualifiers (NocaseDict) –
Qualifier values of the parameter declaration.
Each dictionary item specifies one qualifier value, with:
- key (string): Qualifier name
- value (
CIMQualifier
): Qualifier value
This variable will never be None.
- value – Deprecated: Because the object represents a parameter declaration, this attribute does not make any sense. Accessing it will issue a DeprecationWarning.
The constructor stores the input parameters as-is and does not infer unspecified parameters from the others (like
CIMProperty
does).Parameters: - name (string) –
Name of the parameter.
Must not be None.
- type (string) –
Name of the CIM data type of the parameter (e.g.
"uint8"
).Must not be None.
- reference_class (string) –
Name of the referenced class, for reference parameters.
None is stored as-is.
- is_array (
bool
) –A boolean indicating whether the parameter is an array (True) or a scalar (False).
None is stored as-is.
- array_size (integer) –
The size of the array parameter, for fixed-size arrays.
None means that the array parameter has variable size.
- qualifiers (
dict
or NocaseDict) –Qualifier values of the parameter declaration.
For details about the dictionary items, see the corresponding attribute.
None is interpreted as an empty dictionary.
- value – Deprecated: Because the object represents a parameter declaration, this parameter does not make any sense. Specifying a value other than None will issue a DeprecationWarning.
-
value
¶ Return value attribute (Deprecated).
-
__str__
()[source]¶ Return a short string representation of the
CIMParameter
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMParameter
object that is suitable for debugging.
-
copy
()[source]¶ Return a copy of the
CIMParameter
object.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMParameter
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMParameter
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(indent)[source]¶ Return a unicode string that is a MOF fragment with the parameter definition represented by the
CIMParameter
object.Parameters: indent (integer) – Number of spaces to indent each parameter
- name (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.Variables: - name (unicode string) –
Name of the qualifier.
This variable will never be None.
- value (CIM data type) –
Value of the qualifier.
None means that the value is Null.
For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string in the constructor.
- type (unicode string) –
Name of the CIM data type of the qualifier (e.g.
"uint8"
).This variable will never be None.
- propagated (
bool
) –Indicates whether the qualifier value has been propagated from a superclass to this class.
None means that this information is not available.
- tosubclass (
bool
) –If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True, specifies the ToSubclass flavor (the qualifier value propagates to subclasses); if False specifies the Restricted flavor (the qualifier values does not propagate to subclasses).
None means that this information is not available.
- toinstance (
bool
) –If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True specifies the ToInstance flavor(the qualifier value propagates to instances. If False, specifies that qualifier values do not propagate to instances. There is no flavor corresponding to toinstance=False.
None means that this information is not available.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
- overridable (
bool
) –If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True, specifies the EnableOverride flavor(the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor(the qualifier value is not overridable in subclasses).
None means that this information is not available.
- translatable (
bool
) –If not None, causes an implicit qualifier type to be defined for this qualifier that has the specified flavor.
If True, specifies the Translatable flavor (the qualifier is translatable); if False specifies that the qualfier is not translatable. There is no flavor corresponding to translatable=False.
None means that this information is not available.
The constructor infers optional parameters that are not specified (for example, it infers type from the Python type of value and other information). If the specified parameters are inconsistent, an exception is raised. If an optional parameter is needed for some reason, an exception is raised.
Parameters: - name (string) –
Name of the qualifier.
Must not be None.
- value (CIM data type) –
Value of the qualifier.
None means that the qualifier is Null.
- type (string) –
Name of the CIM data type of the qualifier (e.g.
"uint8"
).None means that the parameter is unspecified, causing the corresponding attribute to be inferred. An exception is raised if it cannot be inferred.
- propagated (
bool
) –If not None, specifies whether the qualifier value has been propagated from a superclass to this class.
None means that this information is not available.
- overridable (
bool
) –If not None, specifies whether the qualifier value is overridable in subclasses.
None means that this information is not available.
- tosubclass (
bool
) –If not None, specifies whether the qualifier value propagates to subclasses.
None means that this information is not available.
- toinstance (
bool
) –If not None, specifies whether the qualifier value propagates to instances.
None means that this information is not available.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
- translatable (
bool
) –If not None, specifies whether the qualifier is translatable.
None means that this information is not available.
-
__str__
()[source]¶ Return a short string representation of the
CIMQualifier
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMQualifier
object that is suitable for debugging.
-
copy
()[source]¶ Return a copy of the
CIMQualifier
object.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMQualifier
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMQualifier
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
(indent=4)[source]¶ Return a unicode string that is a MOF fragment with the qualifier value represented by the
CIMQualifier
object.Parameters: indent (integer) – Number of spaces to indent the second and subsequent lines of a multi-line result. The first line is not indented.
- name (unicode 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.
Variables: - name (unicode string) –
Name of the qualifier.
This variable will never be None.
- type (unicode string) –
Name of the CIM data type of the qualifier (e.g.
"uint8"
).This variable will never be None.
- value (CIM data type) –
Default value of the qualifier.
None means that the value is Null.
For CIM data types string and char16, this attribute will be a unicode string, even when specified as a byte string in the constructor.
- is_array (
bool
) –A boolean indicating whether the qualifier is an array (True) or a scalar (False).
This variable will never be None.
- array_size (integer) –
The size of the array qualifier, for fixed-size arrays.
None means that the array qualifier has variable size, or that it is not an array.
- scopes (NocaseDict) –
Scopes of the qualifier.
Each dictionary item specifies one scope value, with:
- key (string): Scope name, in upper case.
- value (
bool
): Scope value, specifying whether the qualifier has that scope (i.e. can be applied to a CIM element of that kind).
Valid scope names are “CLASS”, “ASSOCIATION”, “REFERENCE”, “PROPERTY”, “METHOD”, “PARAMETER”, “INDICATION”, and “ANY”. None is interpreted as an empty dictionary.
This variable will never be None.
- tosubclass (
bool
) –If True specifies the ToSubclass flavor(the qualifier value propagates to subclasses); if False specifies the Restricted flavor(the qualifier value does not propagate to subclasses).
None means that this information is not available.
- toinstance (
bool
) –If True, specifies the ToInstance flavor. This flavor specifies that the qualifier value propagates to instances. If False, specifies that qualifier values do not propagate to instances. There is no flavor corresponding to toinstance=False.
None means that this information is not available.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances.
- overridable (
bool
) –If True, specifies the EnableOverride flavor(the qualifier value is overridable in subclasses); if False specifies the DisableOverride flavor(the qualifier value is not overridable in subclasses).
None means that this information is not available.
- translatable (
bool
) –If True, specifies the Translatable flavor. This flavor specifies that the qualifier is translatable. If False, specifies that the qualfier is not translatable. There is no flavor corresponding to translatable=False.
None means that this information is not available.
Parameters: - name (string) –
Name of the qualifier.
Must not be None.
- type (string) –
Name of the CIM data type of the qualifier (e.g.
"uint8"
).Must not be None.
- value (CIM data type) –
Default value of the qualifier.
None means a default value of Null.
- is_array (
bool
) –A boolean indicating whether the qualifier is an array (True) or a scalar (False).
Must not be None.
- array_size (integer) –
The size of the array qualifier, for fixed-size arrays.
None means that the array qualifier has variable size.
- scopes (
dict
or NocaseDict) –Scopes of the qualifier.
For details about the dictionary items, see the corresponding attribute.
- overridable (
bool
) –If not None, defines the flavor that defines whether the qualifier value is overridable in subclasses.
None means that this information is not available.
- tosubclass (
bool
) –If not None, specifies the flavor that defines whether the qualifier value propagates to subclasses.
None means that this information is not available.
- toinstance (
bool
) –If not None, specifies the flavor that defines whether the qualifier value propagates to instances.
None means that this information is not available.
Note that DSP0200 has deprecated the presence of qualifier values on CIM instances and this flavor is not defined in DSP0004
- translatable (
bool
) –If not None, specifies the flavor that defines whether the qualifier is translatable.
None means that this information is not available.
-
__str__
()[source]¶ Return a short string representation of the
CIMQualifierDeclaration
object for human consumption.
-
__repr__
()[source]¶ Return a string representation of the
CIMQualifierDeclaration
object that is suitable for debugging.
-
copy
()[source]¶ Return a copy the
CIMQualifierDeclaration
object.
-
tocimxml
()[source]¶ Return the CIM-XML representation of the
CIMQualifierDeclaration
object, as an instance of an appropriate subclass of Element.The returned CIM-XML representation is consistent with DSP0201.
-
tocimxmlstr
(indent=None)[source]¶ Return the CIM-XML representation of the
CIMQualifierDeclaration
object, as a unicode string.The returned CIM-XML representation is consistent with DSP0201.
Parameters: indent (string or integer) – None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the object, as a unicode string.
-
tomof
()[source]¶ Return a unicode string that is a MOF fragment with the qualifier type represented by the
CIMQualifierDeclaration
object.
- name (unicode string) –
Conversion functions¶
This section describes conversion functions that may be useful for purposes such as debugging.
-
pywbem.
tocimxml
(value)[source]¶ Return the CIM-XML representation of the CIM object or CIM data type, as an Element object.
The returned CIM-XML representation is consistent with DSP0201.
Parameters: value (CIM object or CIM data type) – The value. Returns: The CIM-XML representation of the specified value, as an instance of an appropriate subclass of Element. The returned CIM-XML representation is consistent with DSP0201.
-
pywbem.
tocimxmlstr
(value, indent=None)[source]¶ Return the CIM-XML representation of the CIM object or CIM data type, as a unicode string.
The returned CIM-XML representation is consistent with DSP0201.
Parameters: - value (CIM object or CIM data type) – The CIM object or CIM data type to be converted to CIM-XML.
- indent (string or integer) –
None indicates that a single-line version of the XML should be returned, without any whitespace between the XML elements.
Other values indicate that a prettified, multi-line version of the XML should be returned. A string value specifies the indentation string to be used for each level of nested XML elements. An integer value specifies an indentation string of so many blanks.
Returns: The CIM-XML representation of the value, as a unicode string.
-
pywbem.
tocimobj
(type_, value)[source]¶ Return a CIM object representing the specified value and type.
Parameters: - type_ (string) –
The CIM data type name for the CIM object. See CIM data types for valid type names.
If value is a list, type_ must specify the CIM data type name of an item in the list.
- value (CIM data type and some others, see description) –
The value to be represented as a CIM object.
In addition to the Python types listed in CIM data types, the following Python types are supported for this parameter:
- None: The returned object will be None.
- If type_ specifies one of the CIM integer data types:
- If type_ specifies the CIM boolean data type:
- string. The string must be
'true'
or'false'
in any lexical case
- 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.
- type_ (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 |
Note that constructors of pywbem classes that take CIM typed values as input
may support Python types in addition to those shown above. For example, the
CIMProperty
class represents property values of CIM datetime
type internally as CIMDateTime
objects, but its constructor
accepts datetime.timedelta
objects, datetime.datetime
objects, string, in addition to
CIMDateTime
objects.
-
class
pywbem.
CIMType
[source]¶ Base type for all CIM data types defined in this package.
-
cimtype
= None¶ The name of the CIM datatype, as a string. See CIM data types for details.
-
-
class
pywbem.
CIMDateTime
(dtarg)[source]¶ A value of CIM data type datetime.
The object represents either a timezone-aware point in time, or a time interval.
Parameters: dtarg – The value from which the object is initialized, as one of the following types:
- A string object will be interpreted as CIM datetime format (see DSP0004) and will result in a point in time or a time interval.
- A
datetime.datetime
object will result in a point in time. If 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.
-
minutes_from_utc
¶ The timezone offset of this point in time object as +/- minutes from UTC.
A positive value of the timezone offset indicates minutes east of UTC, and a negative value indicates minutes west of UTC.
0, if this object represents a time interval.
-
datetime
¶ The point in time represented by this object, as a
datetime.datetime
object.None if this object represents a time interval.
-
timedelta
¶ The time interval represented by this object, as a
datetime.timedelta
object.None if this object represents a point in time.
-
is_interval
¶ A boolean indicating whether this object represents a time interval (True) or a point in time (False).
-
static
get_local_utcoffset
()[source]¶ Return the timezone offset of the current local timezone as +/- minutes from UTC.
A positive value indicates minutes east of UTC, and a negative value indicates minutes west of UTC.
-
classmethod
now
(tzi=None)[source]¶ Factory method that returns a new
CIMDateTime
object representing the current date and time.The optional timezone information is used to convert the CIM datetime value into the desired timezone. That does not change the point in time that is represented by the value, but it changes the value of the
hhmmss
components of the CIM datetime value to compensate for changes in the timezone offset component.Parameters: tzi ( MinutesFromUTC
) – Timezone information. None means that the current local timezone is used.Returns: A new CIMDateTime
object representing the current date and time.
-
classmethod
fromtimestamp
(ts, tzi=None)[source]¶ Factory method that returns a new
CIMDateTime
object from a POSIX timestamp value and optional timezone information.A POSIX timestamp value is the number of seconds since “the epoch”, i.e. 1970-01-01 00:00:00 UTC. Thus, a POSIX timestamp value is unambiguous w.r.t. the timezone, but it is not timezone-aware.
The optional timezone information is used to convert the CIM datetime value into the desired timezone. That does not change the point in time that is represented by the value, but it changes the value of the
hhmmss
components of the CIM datetime value to compensate for changes in the timezone offset component.Parameters: - ts (integer) – POSIX timestamp value.
- tzi (
MinutesFromUTC
) – Timezone information. None means that the current local timezone is used.
Returns: A new
CIMDateTime
object representing the specified point in time.
-
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.
-
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
.Instances of subclasses of this class can be initialized with the usual input arguments supported by integer, for example:
>>> pywbem.Uint8(42) Uint8(cimtype='uint8', 42) >>> pywbem.Uint8('42') Uint8(cimtype='uint8', 42) >>> pywbem.Uint8('2A', 16) Uint8(cimtype='uint8', 42) >>> pywbem.Uint8('100', 16) Traceback (most recent call last): . . . ValueError: Integer value 256 is out of range for CIM datatype uint8 >>> pywbem.Uint8(100, 10) Traceback (most recent call last): . . . TypeError: int() can't convert non-string with explicit base
-
minvalue
= None¶ The minimum valid value for the integer, according to the capabilities of its CIM data type. See CIM data types for a list of CIM integer data types.
-
maxvalue
= None¶ The maximum valid value for the integer, according to the capabilities of its CIM data type. See CIM data types for a list of CIM integer data types.
-
-
class
pywbem.
Uint8
[source]¶ A value of CIM data type uint8. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
-
class
pywbem.
Sint8
[source]¶ A value of CIM data type sint8. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
-
class
pywbem.
Uint16
[source]¶ A value of CIM data type uint16. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
-
class
pywbem.
Sint16
[source]¶ A value of CIM data type sint16. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
-
class
pywbem.
Uint32
[source]¶ A value of CIM data type uint32. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
-
class
pywbem.
Sint32
[source]¶ A value of CIM data type sint32. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
-
class
pywbem.
Uint64
[source]¶ A value of CIM data type uint64. Derived from
CIMInt
.For details on CIM integer data types, see
CIMInt
.
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 for the namespace parameter ofWBEMConnection
.
Note: For tooling reasons, the constants are shown in the namespace
pywbem.cim_constants
. However, they are also available in the pywbem
namespace and should be used from there.
-
pywbem.cim_constants.
CIM_ERR_FAILED
= 1¶ A general error occurred that is not covered by a more specific error code.
-
pywbem.cim_constants.
CIM_ERR_ACCESS_DENIED
= 2¶ Access to a CIM resource is not available to the client.
-
pywbem.cim_constants.
CIM_ERR_INVALID_NAMESPACE
= 3¶ The target namespace does not exist.
-
pywbem.cim_constants.
CIM_ERR_INVALID_PARAMETER
= 4¶ One or more parameter values passed to the method are not valid.
-
pywbem.cim_constants.
CIM_ERR_INVALID_CLASS
= 5¶ The specified class does not exist.
-
pywbem.cim_constants.
CIM_ERR_NOT_FOUND
= 6¶ The requested object cannot be found. The operation can be unsupported on behalf of the WBEM server in general or on behalf of an implementation of a management profile.
-
pywbem.cim_constants.
CIM_ERR_NOT_SUPPORTED
= 7¶ The requested operation is not supported on behalf of the WBEM server, or on behalf of a provided class. If the operation is supported for a provided class but is not supported for particular instances of that class, then CIM_ERR_FAILED shall be used.
-
pywbem.cim_constants.
CIM_ERR_CLASS_HAS_CHILDREN
= 8¶ The operation cannot be invoked on this class because it has subclasses.
-
pywbem.cim_constants.
CIM_ERR_CLASS_HAS_INSTANCES
= 9¶ The operation cannot be invoked on this class because one or more instances of this class exist.
-
pywbem.cim_constants.
CIM_ERR_INVALID_SUPERCLASS
= 10¶ The operation cannot be invoked because the specified superclass does not exist.
-
pywbem.cim_constants.
CIM_ERR_ALREADY_EXISTS
= 11¶ The operation cannot be invoked because an object already exists.
-
pywbem.cim_constants.
CIM_ERR_NO_SUCH_PROPERTY
= 12¶ The specified property does not exist.
-
pywbem.cim_constants.
CIM_ERR_TYPE_MISMATCH
= 13¶ The value supplied is not compatible with the type.
-
pywbem.cim_constants.
CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED
= 14¶ The query language is not recognized or supported.
-
pywbem.cim_constants.
CIM_ERR_INVALID_QUERY
= 15¶ The query is not valid for the specified query language.
-
pywbem.cim_constants.
CIM_ERR_METHOD_NOT_AVAILABLE
= 16¶ The extrinsic method cannot be invoked.
-
pywbem.cim_constants.
CIM_ERR_METHOD_NOT_FOUND
= 17¶ The specified extrinsic method does not exist.
-
pywbem.cim_constants.
CIM_ERR_NAMESPACE_NOT_EMPTY
= 20¶ The specified namespace is not empty.
-
pywbem.cim_constants.
CIM_ERR_INVALID_ENUMERATION_CONTEXT
= 21¶ The enumeration identified by the specified context cannot be found, is in a closed state, does not exist, or is otherwise invalid.
-
pywbem.cim_constants.
CIM_ERR_INVALID_OPERATION_TIMEOUT
= 22¶ The specified operation timeout is not supported by the WBEM server.
-
pywbem.cim_constants.
CIM_ERR_PULL_HAS_BEEN_ABANDONED
= 23¶ The pull operation has been abandoned due to execution of a concurrent CloseEnumeration operation on the same enumeration.
-
pywbem.cim_constants.
CIM_ERR_PULL_CANNOT_BE_ABANDONED
= 24¶ The attempt to abandon a concurrent pull operation on the same enumeration failed. The concurrent pull operation proceeds normally.
-
pywbem.cim_constants.
CIM_ERR_FILTERED_ENUMERATION_NOT_SUPPORTED
= 25¶ Using a a filter query in pulled enumerations is not supported by the WBEM server.
-
pywbem.cim_constants.
CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
= 26¶ The WBEM server does not support continuation on error.
-
pywbem.cim_constants.
CIM_ERR_SERVER_LIMITS_EXCEEDED
= 27¶ The WBEM server has failed the operation based upon exceeding server limits.
-
pywbem.cim_constants.
CIM_ERR_SERVER_IS_SHUTTING_DOWN
= 28¶ The WBEM server is shutting down and cannot process the operation.
-
pywbem.cim_constants.
DEFAULT_NAMESPACE
= 'root/cimv2'¶ Default CIM namespace
Exceptions¶
The following exceptions are pywbem specific exceptions that can be raised at the WBEM client library API.
-
class
pywbem.
ConnectionError
[source]¶ This exception indicates a problem with the connection to the WBEM server. A retry may or may not succeed. Derived from
Error
.
-
class
pywbem.
AuthError
[source]¶ This exception indicates an authentication error with the WBEM server, either during TLS/SSL handshake, or during HTTP-level authentication. Derived from
Error
.
-
class
pywbem.
HTTPError
(status, reason, cimerror=None, cimdetails=None)[source]¶ This exception indicates that the WBEM server returned an HTTP response with a bad HTTP status code. Derived from
Error
.The args instance variable is a tuple(status, reason, cimerror, cimdetails).
The message instance variable is not set.
Parameters: - status (number) – HTTP status code (e.g. 500).
- reason (string) – HTTP reason phrase (e.g. ‘Internal Server Error’).
- cimerror (string) – Value of the CIMError header field, if present. None, otherwise.
- cimdetails (dict) –
Dictionary with CIMOM-specific header fields with details about the situation reported in the CIMError header field.
- Key: header field name (e.g. PGErrorDetail)
- Value: header field value (i.e. text message)
Passing None will result in an empty dictionary.
-
status
¶ HTTP status code (e.g. 500), as a number.
See RFC2616 for a list of HTTP status codes and reason phrases.
-
reason
¶ HTTP reason phrase (e.g. ‘Internal Server Error’), as a string.
See RFC2616 for a list of HTTP status codes and reason phrases.
-
cimerror
¶ Value of CIMError header field in response, if present, as a string. None, otherwise.
See DSP0200 for a list of values.
-
cimdetails
¶ CIMOM-specific details on the situation reported in the CIMError header field, as a dictionary:
- Key: header field name (e.g. PGErrorDetail).
- Value: header field value.
-
class
pywbem.
TimeoutError
[source]¶ This exception indicates that the client timed out waiting for the WBEM server. Derived from
Error
.
-
class
pywbem.
ParseError
[source]¶ This exception indicates a parsing error with the CIM-XML response returned by the WBEM server, or in the CIM-XML request sent by the WBEM listener. Derived from
Error
.
-
class
pywbem.
CIMError
(status_code, status_description=None)[source]¶ This exception indicates that the WBEM server returned an error response with a CIM status code. Derived from
Error
.In Python 2, any
Exception
object can be accessed by index and slice and will delegate such access to itsException.args
instance variable. In Python 3, that ability has been removed.In its version 0.9, pywbem has added the
status_code
andstatus_description
properties.With all these variations, the following approach for accessesing the CIM status code a
CIMError
object works for all pywbem versions since 0.7.0 and for Python 2 and 3:except CIMError as exc: status_code = exc.args[0]
The following approach is recommended when using pywbem 0.9 or newer, and it works for Python 2 and 3:
except CIMError as exc: status_code = exc.status_code
The following approach is limited to Python 2 and will not work on Python 3, and is therefore not recommended:
except CIMError as exc: status_code = exc[0]
Parameters: - status_code (number) – Numeric CIM status code.
- status_description (string) – CIM status description text returned by the server, representing a human readable message describing the error. None, if the server did not return a description text.
Variables: args – A tuple(status_code, status_description) set from the corresponding init arguments.
-
status_code
¶ Numeric CIM status code.
See CIM status codes for constants defining the numeric CIM status code values.
-
status_code_name
¶ Symbolic name of the CIM status code.
If the CIM status code is invalid, the string
"Invalid status code <code>"
is returned.
-
status_description
¶ CIM status description text returned by the server, representing a human readable message describing the error.
If the server did not return a description, a short default text for the CIM status code is returned. If the CIM status code is invalid, the string
"Invalid status code <code>"
is returned.Note that
args[1]
is always thestatus_description
init argument, without defaulting it to a standard text in case of None.
Security considerations¶
Authentication types¶
Authentication is the act of establishing the identity of a user on the client side to the server, and possibly also of establishing the identity of a server to the client.
There are two levels of authentication in CIM-XML:
TLS/SSL level authentication (only when HTTPS is used):
This kind of authentication is also known as transport level authentication. It is used during the TLS/SSL handshake protocol, before any HTTP requests flow.
In almost all cases (unless an anonymous cipher is used), this involves an X.509 certificate that is presented by the server (therefore called server certificate) and that allows the client to establish the identity of the server.
It optionally involves an X.509 certificate that is presented by the client (therefore called client certificate) and that allows the server to establish the identity of the client or even of the client user, and thus can avoid the use of credentials in the HTTP level authentication.
If a client certificate is used, the authentication scheme at the TLS/SSL level is called 2-way authentication (also known as client authentication or mutual SSL authentication). If a client certificate is not used, the authentication scheme is called 1-way authentication (also known as SSL authentication).
Userid/password credentials do not play any role in TLS/SSL level authentication.
HTTP level authentication:
This kind of authentication is used in HTTP/HTTPS requests and responses (in case of HTTPS, after the TLS/SSL handshake protocol has completed).
In case of Basic Authentication and Digest Authentication (see RFC2617), it involves passing credentials (userid and password) via the
Authenticate
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.
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
WBEM server API¶
The WBEM server API encapsulates certain functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace of the server, or the management profiles advertised by the server.
This chapter has the following sections:
- Example - An example on how to use the API.
- WBEMServer - The
WBEMServer
class serves as a general access point for clients to WBEM servers. It allows determining the Interop namespace of the server, or the advertised management profiles. - ValueMapping - The
ValueMapping
class maps corresponding values of the Values and ValueMap qualifiers of a CIM element and supports the translation of the actual value (often an integer) to the corresponding value of the Values qualifier.
Note
The WBEM server API has been introduced in v0.9.0 as experimental and has been declared final in 0.10.0.
Example¶
The following example code displays some information about a WBEM server:
from pywbem import WBEMConnection, WBEMServer, ValueMapping
def explore_server(server_url, username, password):
print("WBEM server URL:\n %s" % server_url)
conn = WBEMConnection(server_url, (username, password))
server = WBEMServer(conn)
print("Brand:\n %s" % server.brand)
print("Version:\n %s" % server.version)
print("Interop namespace:\n %s" % server.interop_ns)
print("All namespaces:")
for ns in server.namespaces:
print(" %s" % ns)
print("Advertised management profiles:")
org_vm = ValueMapping.for_property(server, server.interop_ns,
'CIM_RegisteredProfile', 'RegisteredOrganization')
for inst in server.profiles:
org = org_vm.tovalues(inst['RegisteredOrganization'])
name = inst['RegisteredName']
vers = inst['RegisteredVersion']
print(" %s %s Profile %s" % (org, name, vers))
Example output:
WBEM server URL:
http://0.0.0.0
Brand:
pegasus
Version:
2.12.0
Interop namespace:
root/PG_Interop
All namespaces:
root/PG_InterOp
root/PG_Internal
root/cimv2
root
Advertised management profiles:
SNIA Indication Profile 1.1.0
SNIA Indication Profile 1.2.0
SNIA Software Profile 1.1.0
SNIA Software Profile 1.2.0
SNIA Profile Registration Profile 1.0.0
SNIA SMI-S Profile 1.2.0
SNIA Server Profile 1.1.0
SNIA Server Profile 1.2.0
DMTF Profile Registration Profile 1.0.0
DMTF Indications Profile 1.1.0
WBEMServer¶
-
class
pywbem.
WBEMServer
(conn)[source]¶ A representation of a WBEM server that serves as a general access point to a client.
It supports determining the Interop namespace of the server, all namespaces, its brand and version, the advertised management profiles and finally allows to retrieve the central instances of a management profile with one method invocation regardless of whether the profile implementation chose the central or scoping class profile advertisement methodology (see DSP1033).
It also provides functions to subscribe for indications.
Parameters: conn ( WBEMConnection
) – Connection to the WBEM server.-
INTEROP_NAMESPACES
= ['interop', 'root/interop', 'root/PG_Interop']¶ A class variable with the possible names of Interop namespaces that should be tried when determining the Interop namespace on the WBEM server.
-
NAMESPACE_CLASSNAMES
= ['CIM_Namespace', '__Namespace']¶ A class variable with the possible names of CIM classes for representing CIM namespaces, that should be tried when determining the namespaces on the WBEM server.
-
__repr__
()[source]¶ Return a representation of the
WBEMServer
object with all attributes, that is suitable for debugging.
-
conn
¶ The connection to the WBEM server, as a
WBEMConnection
object.
-
interop_ns
¶ The name of the Interop namespace of the WBEM server, as a string.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
- Exceptions raised by
-
namespace_classname
¶ The name of the CIM class that was found to represent the CIM namespaces of the WBEM server, as a string.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
- Exceptions raised by
-
namespaces
¶ A list with the names of all namespaces of the WBEM server, each list item being a string.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
- Exceptions raised by
-
brand
¶ Brand of the WBEM server, as a string.
The brand string will be one of the following:
"OpenPegasus"
, for OpenPegasus"SFCB"
, for SFCB- First word of the value of the ElementName property of the CIM_ObjectManager instance, for any other WBEM servers.
"unknown"
, if the ElementName property is Null.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
-
version
¶ Version of the WBEM server, as a string. None, if the version cannot be determined.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
- Exceptions raised by
-
profiles
¶ List of management profiles advertised by the WBEM server, each list item being a
CIMInstance
object representing a CIM_RegisteredProfile instance.Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
- Exceptions raised by
-
get_selected_profiles
(registered_org=None, registered_name=None, registered_version=None)[source]¶ List of management profiles advertised by the WBEM server and filtered by the input parameters for registered_org, registered_name, and registered_version parameters. Each list item is a
CIMInstance
object representing a CIM_RegisteredProfile instance.Parameters: - profile_org (string) – the RegisteredOrganization to match the RegisteredOrganization of the profile. If None, this parameter is ignored in the filter
- profile_name (string) – the RegisteredName. If None, this parameter is ignored in the filter
- profile_version (string) – the RegisteredVersion. If None, this parameter is ignored in the filter
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.KeyError
– If an instance in the list of profiles is incomplete and does not include the required properties.
-
get_central_instances
(profile_path, central_class=None, scoping_class=None, scoping_path=None)[source]¶ Determine the central instances for a management profile, and return their instance paths as a list of
CIMInstanceName
objects.This method supports the following profile advertisement methodologies (see DSP1033), and attempts them in this order:
- GetCentralInstances methodology (new in DSP1033 1.1)
- Central class methodology
- Scoping class methodology
Use of the scoping class methodology requires specifying the central class, scoping class and scoping path defined by the profile. If any of them is None, this method will attempt only the GetCentralInstances and central class methodologies, but not the scoping class methodology. If using these two methodologies does not result in any central instances, and the scoping class methodology cannot be used, an exception is raised.
The scoping path is a directed traversal path from the central instances to the scoping instances. Its first list item is always the association class name of the traversal hop starting at the central instances. For each further traversal hop, the list contains two more items: The class name of the near end of that hop, and the class name of the traversed association. As a result, the class names of the central instances and scoping instances are not part of the list.
Example for a 1-hop traversal:
- central class:
"CIM_Fan"
- scoping path:
["CIM_SystemDevice"]
- scoping class:
"CIM_ComputerSystem"
Example for a 2-hop traversal:
- central class:
"CIM_Sensor"
- scoping path:
["CIM_AssociatedSensor", "CIM_Fan", "CIM_SystemDevice"]
- scoping class:
"CIM_ComputerSystem"
Parameters: - profile_path (
CIMInstanceName
) – Instance path of CIM_RegisteredProfile instance representing the management profile. - central_class (string) –
Class name of central class defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- scoping_class (string) –
Class name of scoping class defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- scoping_path (list of string) –
Scoping path defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
Returns: List of
CIMInstanceName
objects representing the instance paths of the central instances of the management profile.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– Various errors in scoping path traversal.TypeError
– profile_path must be a CIMInstanceName.
-
ValueMapping¶
-
class
pywbem.
ValueMapping
[source]¶ A utility class that translates the values of a corresponding integer-typed CIM element (property, method, parameter) that is qualified with the ValueMap and Values qualifiers, from the element value space into into its Values qualifier space.
This is done by retrieving the CIM class definition defining the CIM element in question, and by inspecting its ValueMap and Values qualifiers.
The actual translation of the values is performed by the
tovalues()
method.Instances of this class should be created through one of the factory class methods:
for_property()
,for_method()
, orfor_parameter()
.Value ranges (
"2..4"
) and the indicator for unclaimed values (".."
) in the ValueMap qualifier are supported.Example: Given the following definition of a property in MOF:
[ValueMap{ "0", "2..4", "..6", "7..", "9", ".." }, Values{ "zero", "two-four", "five-six", "seven-eight", "nine", "unclaimed"}] uint16 MyProp;
The following code will create a value mapping for this property and will print a few integer values and their Values strings:
vm = pywbem.ValueMapping.for_property(server, namespace, classname, "MyProp") for value in range(0, 12): print("value: %s, Values string: %r" % (value, vm.tovalues(value)) Results: value: 0, Values string: 'zero' value: 1, Values string: 'unclaimed' value: 2, Values string: 'two-four' value: 3, Values string: 'two-four' value: 4, Values string: 'two-four' value: 5, Values string: 'five-six' value: 6, Values string: 'five-six' value: 7, Values string: 'seven-eight' value: 8, Values string: 'seven-eight' value: 9, Values string: 'nine' value: 10, Values string: 'unclaimed' value: 11, Values string: 'unclaimed'
-
classmethod
for_property
(server, namespace, classname, propname)[source]¶ Factory method that returns a new
ValueMapping
instance corresponding to a CIM property.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMServer
) – The WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the property. The property can be defined in that class or inherited into that class.
- propname (string) – Name of the CIM property that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– No Values qualifier defined.TypeError
– The property is not integer-typed.
- server (
-
classmethod
for_method
(server, namespace, classname, methodname)[source]¶ Factory method that returns a new
ValueMapping
instance corresponding to a CIM method.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMServer
) – The WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
- methodname (string) – Name of the CIM method that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– No Values qualifier defined.TypeError
– The method is not integer-typed.
- server (
-
classmethod
for_parameter
(server, namespace, classname, methodname, parametername)[source]¶ Factory method that returns a new
ValueMapping
instance corresponding to a CIM parameter.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMServer
) – The WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
- methodname (string) – Name of the CIM method that has the parameter.
- parametername (string) – Name of the CIM parameter that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– No Values qualifier defined.TypeError
– The parameter is not integer-typed.
- server (
-
element
¶ Return the corresponding CIM element of this instance, as a CIM object (
CIMProperty
,CIMMethod
, orCIMParameter
).
-
tovalues
(element_value)[source]¶ Return the Values string for an element value, based on the ValueMap / Values qualifiers of the corresponding CIM element.
Parameters: element_value (integer or
CIMInt
) – The value of the CIM element.Returns: The Values string for the element value.
Return type: Raises: ValueError
– Element value outside of the set defined by ValueMap.ValueError
– No Values qualifier defined.ValueError
– Invalid ValueMap entry.TypeError
– The CIM element is not integer-typed.TypeError
– Element value is not an integer type.
-
classmethod
WBEM indication API¶
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.
Note
The WBEM indication API has been introduced in v0.9.0 as experimental and has been declared final in 0.10.0.
WBEMListener¶
The WBEMListener
class provides a thread-based WBEM listener
service that can receive CIM indications from multiple WBEM servers and that
calls registered callback functions to deliver the received indications.
Examples¶
The following example creates and runs a listener:
import sys
import logging
from socket import getfqdn
from pywbem import WBEMListener
def process_indication(indication, host):
'''This function gets called when an indication is received.'''
print("Received CIM indication from {host}: {ind!r}". \
format(host=host, ind=indication))
def main():
logging.basicConfig(stream=sys.stderr, level=logging.WARNING,
format='%(asctime)s - %(levelname)s - %(message)s)
certkeyfile = 'listener.pem'
url1 = 'http://server1'
conn1 = WBEMConnection(url1)
server1 = WBEMServer(conn1)
server1.determine_interop_ns()
url2 = 'http://server2'
conn2 = WBEMConnection(url2)
server2 = WBEMServer(conn2)
server2.validate_interop_ns('root/PG_InterOp')
my_listener = WBEMListener(host=getfqdn()
http_port=5988,
https_port=5989,
certfile=certkeyfile,
keyfile=certkeyfile)
my_listener.add_callback(process_indication)
listener.start()
# listener runs until executable terminated
# or listener.stop()
See the example in section WBEMSubscriptionManager for an example of using a listener in combination with a subscription manager.
Another listener example is in the script examples/listen.py
(when you
clone the GitHub pywbem/pywbem project). It is an interactive Python shell that
creates a listener and displays any indications it receives, in MOF format.
-
class
pywbem.
WBEMListener
(host, http_port=None, https_port=None, certfile=None, keyfile=None)[source]¶ A WBEM listener.
The listener supports starting and stopping threads that listen for CIM-XML ExportIndication messages using HTTP and/or HTTPS, and that pass any received indications on to registered callback functions.
Parameters: - host (string) – IP address or host name this listener can be reached at.
- http_port (string or integer) –
HTTP port this listener can be reached at. Note that at least one port (HTTP or HTTPS) must be set
None means not to set up a port for HTTP.
- https_port (string or integer) –
HTTPS port this listener can be reached at.
None means not to set up a port for HTTPS.
- certfile (string) –
File path of certificate file to be used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
It is valid for the certificate file to contain a private key; the server certificate sent during SSL/TLS handshake is sent without the private key.
None means not to use a server certificate file. Setting up a port for HTTPS requires specifying a certificate file.
- keyfile (string) –
File path of private key file to be used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
It is valid to specify a certificate file that contains a private key.
None means not to use a private key file. Setting up a port for HTTPS requires specifying a private key file.
-
__repr__
()[source]¶ Return a representation of the
WBEMListener
object with all attributes, that is suitable for debugging.
-
http_port
¶ The HTTP port this listener can be reached at, as an integer.
None means there is no port set up for HTTP.
-
https_port
¶ The HTTPS port this listener can be reached at, as an integer.
None means there is no port set up for HTTPS.
-
certfile
¶ The file path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
None means there is no certificate file being used (that is, no port is set up for HTTPS).
-
keyfile
¶ The file path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
None means there is no certificate file being used (that is, no port is set up for HTTPS).
-
logger
¶ The logger object for this listener.
Each listener object has its own separate logger object that is created via
logging.getLogger()
.The name of this logger object is:
pywbem.listener.{id}
where
{id}
is theid()
value of the listener object. Users of the listener should not look up the logger object by name, but should use this property to get to it.By default, this logger uses the
NullHandler
log handler, and its log level islogging.NOTSET
. This causes this logger not to emit any log messages and to propagate them to the Python root logger.The behavior of this logger can be changed by invoking its methods (see
logging.Logger
). The behavior of the root logger can for example be configured usinglogging.basicConfig()
:import sys import logging logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format='%(asctime)s - %(levelname)s - %(message)s')
-
start
()[source]¶ Start the WBEM listener threads, if they are not yet running.
A thread serving CIM-XML over HTTP is started if an HTTP port was specified for the listener. A thread serving CIM-XML over HTTPS is started if an HTTPS port was specified for the listener.
These server threads will handle the ExportIndication export message described in DSP0200 and they will invoke the registered callback functions for any received CIM indications.
These server threads can be stopped using the
stop()
method. They will be automatically stopped when the main thread terminates.
-
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]¶ 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¶
The WBEMSubscriptionManager
class is a subscription manager
that provides for creating and removing indication subscriptions (including
indication filters and listener destinations) for multiple WBEM servers and
multiple WBEM listeners and for getting information about existing indication
subscriptions.
The WBEM listener is identified through its URL, so it may be a
WBEMListener
object or any external WBEM listener.
This subscription manager supports three types of ownership for subscription, filter and listener destination CIM instances in WBEM servers:
Owned
Owned CIM instances are created via the subscription manager and their life cycle is bound to the life cycle of the registration of that WBEM server with the subscription manager via
add_server()
.Owned CIM instances are deleted automatically when their WBEM server is deregistered from the subscription manager via
remove_server()
orremove_all_servers()
. They can still explicitly 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 that cannot be deleted (or created) by a WBEM client.
If a client creates a subscription between a filter and a listener destination, the types of ownership of these three CIM instances may be arbitrarily mixed, with one exception:
- A permanent subscription cannot be created on an owned filter or an owned
listener destination. Allowing that would prevent the automatic life cycle
management of the owned filter or listener destination by the subscription
manager. This restriction is enforced by the
WBEMSubscriptionManager
class.
The WBEMSubscriptionManager
object remembers owned
subscriptions, filters, and listener destinations. If for some reason that
object gets deleted before all servers could be removed (e.g. because the
Python program aborts), the corresponding CIM instances in the WBEM server
still exist, but the knowledge is lost that these instances were owned by that
subscription manager. Therefore, the subscription manager discovers owned
subscriptions, filters, and listener destinations when a server is added.
For filters, this discovery is based upon the Name property. Therefore, if
the Name property is set by the user (e.g. because a management profile
requires a particular name), the filter must be permanent and cannot be owned.
Examples¶
The following example code demonstrates the use of a subscription manager to subscribe for a CIM alert indication on a WBEM server. The WBEM listener is assumed to exist somewhere and is identified by its URL:
import sys
from socket import getfqdn
from pywbem import WBEMConnection, WBEMServer, WBEMSubscriptionManager
server_url = 'http://myserver'
server_credentials = (user, password)
listener_url = 'http://mylistener'
conn = WBEMConnection(server_url, server_credentials)
server = WBEMServer(conn)
sub_mgr = WBEMSubscriptionManager(subscription_manager_id='fred')
# Register the server in the subscription manager:
server_id = sub_mgr.add_server(server)
# Add a listener destination in the server:
dest_inst = sub_mgr.add_listener_destinations(server_id, listener_url)
# Subscribe to a static filter of a given name:
filter1_name = "DMTF:Indications:GlobalAlertIndicationFilter"
filter1_insts = sub_mgr.get_all_filters(server_id)
for inst in filter1_insts:
if inst['Name'] == filter1_name:
sub_mgr.add_subscriptions(server_id, inst.path, dest_inst.path)
break
# Create a dynamic alert filter and subscribe to it:
filter2_source_ns = "root/cimv2"
filter2_query = "SELECT * FROM CIM_AlertIndication " \
"WHERE OwningEntity = 'DMTF' " \
"AND MessageID LIKE 'SVPC0123|SVPC0124|SVPC0125'"
filter2_language = "DMTF:CQL"
filter2_inst = subscription_manager.add_filter(server_id,
filter2_source_ns, filter2_query, filter2_language, owned=True,
filter_id="myalert")
sub_mgr.add_subscriptions(server_id, filter2_inst.path, dest_inst.path)
The following example code briefly shows how to use a subscription manager as a context manager, in order to get automatic cleanup of owned instances:
with WBEMSubscriptionManager('fred') as sub_mgr:
server_id = sub_mgr.add_server(server)
. . .
# The exit method automatically calls remove_all_servers(), which deletes
# all owned subscription, filter and destination instances in the servers
# that were registered.
The Tutorial section contains a tutorial about the subscription manager.
-
class
pywbem.
WBEMSubscriptionManager
(subscription_manager_id)[source]¶ A class for managing subscriptions for CIM indications in a WBEM server.
The class may be used as a Python context manager, in order to get automatic clean up (see
__exit__()
).Parameters: subscription_manager_id (string) – A subscription manager ID string that is used as a component in the value of the Name property of indication filter and listener destination instances to help the user identify these instances in a WBEM server.
Must not be None.
The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.
The subscription manager ID must be unique on the current host.
For example, the form of the Name property of a filter instance is (for details, see
add_filter()
):"pywbemfilter:" {ownership} ":" {subscription_manager_id} ":" {filter_id} ":" {guid}
Raises: ValueError, TypeError for incorrect input parameters. -
__repr__
()[source]¶ Return a representation of the
WBEMSubscriptionManager
object with all attributes, that is suitable for debugging.
-
__enter__
()[source]¶ Enter method when the class is used as a context manager. Returns the subscription manager object
-
__exit__
(exc_type, exc_value, traceback)[source]¶ Exit method when the class is used as a context manager.
It cleans up by calling
remove_all_servers()
.
-
add_server
(server)[source]¶ Register a WBEM server with the subscription manager. This is a prerequisite for adding listener destinations, indication filters and indication subscriptions to the server.
This method discovers listener destination, indication filter, and subscription instances in the WBEM server that are owned by this subscription manager, and registers them in the subscription manager as if they had been created through it.
In this discovery process, listener destination and indication filter instances are matched based upon the value of their Name property. Subscription instances are matched based upon the ownership of the referenced destination and filter instances: If a subscription references a filter or a destination that is owned by this subscription manager, it is considered owned by this subscription manager as well.
Parameters: server (
WBEMServer
) – The WBEM server.Returns: An ID for the WBEM server, for use by other methods of this class.
Return type: Raises: - Exceptions raised by
WBEMConnection
. - ValueError, TypeError for incorrect input parameters.
- 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 that were created by this subscription manager for that server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Raises: Exceptions raised by WBEMConnection
.
-
remove_all_servers
()[source]¶ Remove all registered WBEM servers from the subscription manager. This also unregisters listeners from these servers and removes all owned indication subscriptions, owned indication filters, and owned listener destinations that were created by this subscription manager.
This is, in effect, a complete shutdown of the subscription manager.
Raises: Exceptions raised by WBEMConnection
.
-
add_listener_destinations
(server_id, listener_urls, owned=True)[source]¶ Register WBEM listeners to be the target of indications sent by a WBEM server.
This function automatically creates a listener destination instance (of CIM class “CIM_ListenerDestinationCIMXML”) for each specified listener URL in the Interop namespace of the specified WBEM server.
The form of the Name property of the created destination instance is:
"pywbemdestination:" {ownership} ":" {subscription_manager_id} ":" {guid}
where
{ownership}
is"owned"
or"permanent"
dependent on theowned
argument;{subscription_manager_id}
is the subscription manager ID; and{guid}
is a globally unique identifier.Owned listener destinations are added or updated conditionally: If the listener destination instance to be added is already registered with this subscription manager and has the same property values, it is not created or modified. It it has the same path but different property values, it is modified to get the desired property values. If an instance with this path does not exist yet (the normal case), it is created.
Permanent listener destinations are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - listener_urls (string or list of string) –
The URL or URLs of the WBEM listeners to be registered.
The WBEM listener may be a
WBEMListener
object or any external WBEM listener.Each listener URL string must have the format:
[{scheme}://]{host}:{port}
The following URL schemes are supported:
https
: Causes HTTPS to be used.http
: Causes HTTP to be used. This is the default
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986
with the extensions for zone identifiers as defined in
RFC6874, supporting
-
(minus) for the delimiter before the zone ID string, as an additional choice to%25
.
Note that the port is required in listener URLs.
See
WBEMConnection
for examples of valid URLs, with the caveat that the port in server URLs is optional. - owned (
bool
) – Defines the ownership type of the created listener destination instances: If True, they will be owned. Otherwise, they will be permanent. See WBEMSubscriptionManager for details about these ownership types.
Returns: The created listener destination instances for the defined listener URLs.
Return type: list
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 owned listener destinations in a WBEM server that have been created by this subscription manager.
This function accesses only the local list of owned destinations; it does not contact the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The listener destination instances. Return type: list
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 thename
parameter.This should be used in cases where the user needs to have control over the filter name (e.g. because a DMTF management profile requires a particular name), but it cannot be used for owned filters.
indirectly by specifying the
filter_id
parameter.In this case, the value of the
Name
property will be:"pywbemfilter:" {ownership} ":" {subscription_manager_id} ":" {filter_id} ":" {guid}
where
{ownership}
is"owned"
or"permanent"
dependent on whether the filter is owned or permmanent;{subscription_manager_id}
is the subscription manager ID;{filter_id}
is the filter ID; and{guid}
is a globally unique identifier.This can be used for both owned and permanent filters.
Owned indication filters are added or updated conditionally: If the indication filter instance to be added is already registered with this subscription manager and has the same property values, it is not created or modified. It it has the same path but different property values, it is modified to get the desired property values. If an instance with this path does not exist yet (the normal case), it is created.
Permanent indication filters are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - source_namespace (string) – Source namespace of the indication filter.
- query (string) – Filter query in the specified query language.
- query_language (string) –
Query language for the specified filter query.
Examples: ‘WQL’, ‘DMTF:CQL’.
- owned (
bool
) – Defines the ownership type of the created indication filter instance: If True, it will be owned. Otherwise, it will be permanent. See WBEMSubscriptionManager for details about these ownership types. - filter_id (string) –
A filter ID string that is used as a component in the value of the Name property of filter instances to help the user identify these instances in a WBEM server, or None if the
name
parameter is specified.The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.
There is no requirement that the filter ID be unique. This can be used to identify groups of filters by using the same value for multiple filters.
- name (string) – The filter name to be used directly for the Name property of the
filter instance, or None if the
filter_id
parameter is specified.
Returns: The created indication filter instance.
Return type: Raises: - Exceptions raised by
WBEMConnection
. - ValueError, TypeError for incorrect input parameters.
-
get_owned_filters
(server_id)[source]¶ Return the owned indication filters in a WBEM server that have been created by this subscription manager.
This function accesses only the local list of owned filters; it does not contact the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The indication filter instances. Return type: list
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. It it has the same path but different property values, it is modified to get the desired property values. If an instance with this path does not exist yet (the normal case), it is created.
Permanent subscriptions are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.
Upon successful return of this method, the added subscriptions are active, so that the specified WBEM listeners may immediately receive indications.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - filter_path (
CIMInstanceName
) – Instance path of the indication filter instance in the WBEM server that specifies the indications to be sent. - destination_paths (
CIMInstanceName
or list 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 for incorrect input parameters.
- server_id (string) – The server ID of the WBEM server, returned by
-
get_owned_subscriptions
(server_id)[source]¶ Return the owned indication subscriptions for a WBEM server that have been created by this subscription manager.
This function accesses only the local list of owned subscriptions; it does not contact the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The indication subscription instances. Return type: list
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 are specified, is called MOF (for Managed Object Format). It is defined in DSP0004.
The pywbem package includes a MOF compiler.
MOF compilers take MOF files as input, compile them and the result is used to update a target CIM repository. The repository may initially be empty, or may contain the result of earlier MOF compilations that are used to resolve dependencies the new MOF compilation may have.
The MOF compiler in this package also has an option to remove CIM elements from the repository it has a definition for in the MOF files it processes.
The MOF compiler API provides for invoking the MOF compiler and for plugging in your own CIM repository into the MOF compiler.
The MOF compiler API is available in the pywbem.mof_compiler
module.
This chapter has the following sections:
- MOFCompiler - 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, in addition to the exceptions that can be raised by the WBEM client library API.
MOFCompiler¶
-
class
pywbem.mof_compiler.
MOFCompiler
(handle, search_paths=None, verbose=False, log_func=<function _print_logger>)[source]¶ A MOF compiler.
A MOF compiler is associated with a CIM repository. The repository is used for looking up dependent CIM elements (e.g. the superclass specified in a class whose MOF definition is being compiled), and it is also updated with the result of the compilation. A repository contains CIM namespaces, and the namespaces contain CIM classes, instances and qualifier types.
The association with a CIM repository is established when creating an instance of this class. The interactions with the CIM repository are defined in the abstract base class
BaseRepositoryConnection
.Parameters: - handle (BaseRepositoryConnection) –
A connection to the CIM repository that will be associated with the MOF compiler.
None means that no CIM repository will be associated. In this case, the MOF compiler can only process standalone MOF that does not depend on existing CIM elements in the repository.
- search_paths (iterable of string) – An iterable of path names of directories where MOF include files should be looked up.
- verbose (
bool
) – Indicates whether to issue more detailed compiler messages. - log_func (callable) – A logger function that is invoked for each compiler message. The logger function must take one parameter of string type. The default logger prints to stdout.
-
compile_string
(mof, ns, filename=None)[source]¶ Compile a string of MOF statements into a namespace of the associated CIM repository.
Parameters: - mof (string) – The string of MOF statements to be compiled.
- ns (string) – The name of the CIM namespace in the associated CIM repository that is used for lookup of any dependent CIM elements, and that is also the target of the compilation.
- filename (string) – The path name of the file that the MOF statements were read from. This information is used only in compiler messages.
Raises: MOFParseError
– Syntax error in the MOF.- Any exceptions that are raised by the repository connection class.
-
compile_file
(filename, ns)[source]¶ Compile a MOF file into a namespace of the associated CIM repository.
Parameters: Raises: MOFParseError
– Syntax error in the MOF.- Any exceptions that are raised by the repository connection class.
-
find_mof
(classname)[source]¶ Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler.
The MOF file is found based on its file name: It is assumed that the base part of the file name is the CIM class name.
Example: The class “CIM_ComputerSystem” is expected to be in a file “CIM_ComputerSystem.mof”.
Parameters: classame (string) – The name of the CIM class to look up. Returns: A string with the path name of the MOF file, if it was found. None, otherwise.
- handle (BaseRepositoryConnection) –
Repository connections¶
-
class
pywbem.mof_compiler.
BaseRepositoryConnection
[source]¶ An abstract base class for implementing repository connections for the MOF compiler. This class defines the interface that is used by the MOF compiler (class
MOFCompiler
) when it interacts with the repository.Class
MOFCompiler
invokes only the operations that are defined as methods on this class. Specifically, it does not invoke:- EnumerateInstances
- GetInstance
- EnumerateClasses
- EnumerateClassNames
- association or query operations
- method invocations
Exceptions:
Implementation classes should raise only exceptions derived fromError
. Other exceptions are considered programming errors.-
default_namespace
¶ The default repository namespace, as a string (readable and writeable).
-
EnumerateInstanceNames
(*args, **kwargs)[source]¶ Enumerate instance paths of CIM instances in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.EnumerateInstanceNames()
.
-
CreateInstance
(*args, **kwargs)[source]¶ Create a CIM instance in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.CreateInstance()
.
-
ModifyInstance
(*args, **kwargs)[source]¶ Modify a CIM instance in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.ModifyInstance()
.
-
DeleteInstance
(*args, **kwargs)[source]¶ Delete a CIM instance in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.DeleteInstance()
.
-
GetClass
(*args, **kwargs)[source]¶ Retrieve a CIM class from the repository.
For a description of the parameters, see
pywbem.WBEMConnection.GetClass()
.
-
ModifyClass
(*args, **kwargs)[source]¶ Modify a CIM class in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.ModifyClass()
.
-
CreateClass
(*args, **kwargs)[source]¶ Create a CIM class in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.CreateClass()
.
-
DeleteClass
(*args, **kwargs)[source]¶ Delete a CIM class in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.DeleteClass()
.
-
EnumerateQualifiers
(*args, **kwargs)[source]¶ Enumerate the qualifier types in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.EnumerateQualifiers()
.
-
GetQualifier
(*args, **kwargs)[source]¶ Retrieve a qualifier type from the repository.
For a description of the parameters, see
pywbem.WBEMConnection.GetQualifier()
.
-
SetQualifier
(*args, **kwargs)[source]¶ Create or modify a qualifier type in the repository.
For a description of the parameters, see
pywbem.WBEMConnection.SetQualifier()
.
-
DeleteQualifier
(*args, **kwargs)[source]¶ Delete a qualifier type from the repository.
For a description of the parameters, see
pywbem.WBEMConnection.DeleteQualifier()
.
-
class
pywbem.mof_compiler.
MOFWBEMConnection
(conn=None)[source]¶ A repository connection that stores CIM elements locally in the instance of this class. It also supports removal of CIM elements via its
rollback()
method, by rolling back the changes applied locally to the instance.It is instantiated on top of an underlying repository connection that is connected with the CIM repository that is actually being updated.
This class implements the
BaseRepositoryConnection
interface.Exceptions:
The methods of this class may raise any exceptions described for classWBEMConnection
.Parameters: conn (BaseRepositoryConnection) – The underlying repository connection.
None means that there is no underlying repository and all operations performed through this object will fail.
-
getns
()¶ Return either connection default or universal default namespace
-
setns
(value)¶ Set the namespace in value into either the connection default or package wide default namespace
-
default_namespace
¶ The default repository namespace, as a string (readable and writeable).
-
EnumerateInstanceNames
(*args, **kwargs)[source]¶ This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND. Because the operations of this class silently create every namespace that is needed and never return that error, this method is never called, and is therefore not implemented.
-
ModifyInstance
(*args, **kwargs)[source]¶ This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance. Because
CreateInstance()
overwrites existing instances, this method is never called, and is therefore not implemented.
-
CreateInstance
(*args, **kwargs)[source]¶ Create a CIM instance in the local repository of this class.
For a description of the parameters, see
pywbem.WBEMConnection.CreateInstance()
.
-
DeleteInstance
(*args, **kwargs)[source]¶ This method is only invoked by
rollback()
(on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
-
GetClass
(*args, **kwargs)[source]¶ Retrieve a CIM class from the local repository of this class.
For a description of the parameters, see
pywbem.WBEMConnection.GetClass()
.
-
ModifyClass
(*args, **kwargs)[source]¶ This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class. Because
CreateClass()
overwrites existing classes, this method is never called, and is therefore not implemented.
-
CreateClass
(*args, **kwargs)[source]¶ Create a CIM class in the local repository of this class.
For a description of the parameters, see
pywbem.WBEMConnection.CreateClass()
.
-
DeleteClass
(*args, **kwargs)[source]¶ This method is only invoked by
rollback()
(on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
-
EnumerateQualifiers
(*args, **kwargs)[source]¶ Enumerate the qualifier types in the local repository of this class.
For a description of the parameters, see
pywbem.WBEMConnection.EnumerateQualifiers()
.
-
GetQualifier
(*args, **kwargs)[source]¶ Retrieve a qualifier type from the local repository of this class.
For a description of the parameters, see
pywbem.WBEMConnection.GetQualifier()
.
-
SetQualifier
(*args, **kwargs)[source]¶ Create or modify a qualifier type in the local repository of this class.
For a description of the parameters, see
pywbem.WBEMConnection.SetQualifier()
.
-
DeleteQualifier
(*args, **kwargs)[source]¶ This method is only invoked by
rollback()
(on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
-
Exceptions¶
-
class
pywbem.mof_compiler.
MOFParseError
(parser_token=None, msg=None)[source]¶ Exception raised when MOF cannot be parsed correctly, e.g. for syntax errors. Derived from
Error
.Parameters: - parser_token – PLY parser token for the error (that is, the
p
argument of a PLY parser function). This token contains information on the location of the error in the MOF file, which is copied into this object, and is accessible via properties. - msg (string) – Message text supplied by the creator of the error
-
lineno
¶ Line number in the MOF file where the error occurred.
-
column
¶ Position within the line where the error occurred.
-
context
¶ Context string that can be inserted when printing the error message. The context string consists of a first line with a segment of the MOF surrounding the error position, and a second line that uses the ‘^’ character to indicate the token in error.
- 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 creates, updates or removes CIM instances, classes or qualifier types in a CIM repository.
-
A WBEM command line interface that provides an interactive Python environment for issuing WBEM operations to a WBEM server.
mof_compiler¶
The mof_compiler
command is a MOF compiler. It compiles MOF files, and
updates the repository of a WBEM server with the result.
The MOF compiler can also be invoked from programs via the MOF compiler API.
The MOF compiler has a pluggable interface for the CIM repository. The default implementation of that interface uses a WBEM server as its repository. The plug interface is also described in the MOF compiler API.
Usage¶
Here is the help text of the command:
usage: mof_compiler [options] moffile ...
Compile MOF files, and update a namespace in a WBEM server with the result.
Positional arguments:
moffile Path name of the MOF file to be compiled.
Can be specified multiple times.
Server related options:
Specify the WBEM server and namespace the MOF compiler works against, for
looking up existing elements, and for applying the MOF compilation results
to.
-s url, --server url Host name or URL of the WBEM server (required),
in this format:
[scheme://]host[:port]
- scheme: Defines the protocol to use:
- "https" for HTTPS protocol
- "http" for HTTP protocol
Default: "https".
- host: Defines host name as follows:
- short or fully qualified DNS hostname
- literal IPV4 address(dotted)
- literal IPV6 address (RFC 3986) with zone
identifier extensions(RFC 6874)
supporting "-" or %25 for the delimiter
- port: Defines the WBEM server port to be used.
Defaults:
- 5988, when using HTTP
- 5989, whenusing HTTPS
-n namespace, --namespace namespace
Namespace in the WBEM server.
Default: root/cimv2
Connection security related options:
Specify user name and password or certificates and keys
-u user, --user user User name for authenticating with the WBEM server.
Default: No user name.
-p password, --password password
Password for authenticating with the WBEM server.
Default: Will be prompted for, if user name
specified.
-nvc, --no-verify-cert
Client will not verify certificate returned by the
WBEM server (see cacerts). This bypasses the client-
side verification of the server identity, but allows
encrypted communication with a server for which the
client does not have certificates.
--cacerts cacerts File or directory containing certificates that will be
matched against a certificate received from the WBEM
server. Set the --no-verify-cert option to bypass
client verification of the WBEM server certificate.
Default: Searches for matching certificates in the
following system directories:
/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
/etc/ssl/certs
/etc/ssl/certificates
--certfile certfile Client certificate file for authenticating with the
WBEM server. If option specified the client attempts
to execute mutual authentication.
Default: Simple authentication.
--keyfile keyfile Client private key file for authenticating with the
WBEM server. Not required if private key is part of the
certfile option. Not allowed if no certfile option.
Default: No client key file. Client private key should
then be part of the certfile
Action related options:
Specify actions against the WBEM server's namespace. Default:
Create/update elements.
-r, --remove Remove elements (found in the MOF files) from the WBEM
server's namespace, instead of creating or updating
them
-d, --dry-run Don't actually modify the WBEM server's namespace,
just check MOF syntax. Connection to WBEM server is
still required to check qualifiers.
General options:
-I dir, --include dir
Path name of a MOF include directory. Can be specified
multiple times.
-v, --verbose Print more messages while processing
-h, --help Show this help message and exit
Example: mof_compiler CIM_Schema_2.45.mof -s https://localhost -n root/cimv2
-u sheldon -p p42
wbemcli¶
The wbemcli
command is a WBEM client command line interface (CLI). It is
implemented as an interactive shell.
The WBEM client CLI does not have an external API on its own; it is for the most part a consumer of the WBEM client library API.
Usage¶
Here is the help text of the command:
usage: wbemcli [options] server
Provide an interactive shell for issuing operations against a WBEM server.
wbemcli executes the WBEMConnection as part of initialization so the user can
input requests as soon as the interactive shell is started.
Use h() in thenteractive shell for help for wbemcli methods and variables.
Positional arguments:
server Host name or url of the WBEM server in this format:
[{scheme}://]{host}[:{port}]
- scheme: Defines the protocol to use;
- "https" for HTTPs protocol
- "http" for HTTP protocol.
Default: "https".
- host: Defines host name as follows:
- short or fully qualified DNS hostname,
- literal IPV4 address(dotted)
- literal IPV6 address (RFC 3986) with zone
identifier extensions(RFC 6874)
supporting "-" or %25 for the delimiter.
- port: Defines the WBEM server port to be used
Defaults:
- HTTP - 5988
- HTTPS - 5989
Server related options:
Specify the WBEM server namespace and timeout
-n namespace, --namespace namespace
Default namespace in the WBEM server for operation
requests when namespace option not supplied with
operation request.
Default: root/cimv2
-t timeout, --timeout timeout
Timeout of the completion of WBEM Server operation
in seconds(integer between 0 and 300).
Default: No timeout
Connection security related options:
Specify user name and password or certificates and keys
-u user, --user user User name for authenticating with the WBEM server.
Default: No user name.
-p password, --password password
Password for authenticating with the WBEM server.
Default: Will be prompted for, if user name
specified.
-nvc, --no-verify-cert
Client will not verify certificate returned by the
WBEM server (see cacerts). This bypasses the client-
side verification of the server identity, but allows
encrypted communication with a server for which the
client does not have certificates.
--cacerts cacerts File or directory containing certificates that will be
matched against a certificate received from the WBEM
server. Set the --no-verify-cert option to bypass
client verification of the WBEM server certificate.
Default: Searches for matching certificates in the
following system directories:
/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
/etc/ssl/certs
/etc/ssl/certificates
--certfile certfile Client certificate file for authenticating with the
WBEM server. If option specified the client attempts
to execute mutual authentication.
Default: Simple authentication.
--keyfile keyfile Client private key file for authenticating with the
WBEM server. Not required if private key is part of the
certfile option. Not allowed if no certfile option.
Default: No client key file. Client private key should
then be part of the certfile
General options:
-s [scripts [scripts ...]], --scripts [scripts [scripts ...]]
Execute the python code defined by the script before the
user gets control. This argument may be repeated to load
multiple scripts or multiple scripts may be listed for a
single use of the option. Scripts are executed after the
WBEMConnection call
-v, --verbose Print more messages while processing
-h, --help Show this help message and exit
Examples:
wbemcli https://localhost:15345 -n vendor -u sheldon -p penny
- (https localhost, port=15345, namespace=vendor user=sheldon
password=penny)
wbemcli http://[2001:db8::1234-eth0] -(http port 5988 ipv6, zone id eth0)
Global functions¶
The interactive shell of wbemcli provides global functions for the CIM operations, and some functions for help display and debugging.
For tooling reasons, these functions are shown as members of the ‘wbemcli’ namespace. However, they are directly available in the namespace of the wbemcli interactive shell.
-
wbemcli.
ein
(cn, ns=None)[source]¶ WBEM operation: EnumerateInstanceNames
Enumerate the instance paths of instances of a class (including instances of its subclasses) in a namespace.
Parameters: - cn (string or CIMClassName) –
Name of the class to be enumerated (case independent).
If specified as a CIMClassName object, its host attribute will be ignored.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
Returns: The instance paths, with their attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: None, indicating the WBEM server is unspecified.
Return type: list of CIMInstanceName
- cn (string or CIMClassName) –
-
wbemcli.
ei
(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None)[source]¶ WBEM operation: EnumerateInstances
Enumerate the instances of a class (including instances of its subclasses) in a namespace.
Parameters: - cn (string or CIMClassName) –
Name of the class to be enumerated (case independent).
If specified as a CIMClassName object, its host attribute will be ignored.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- lo (bool) –
LocalOnly flag: Exclude inherited properties.
If None, this parameter will not be sent to the server, and the server default of True will be used.
Deprecated: Server implementations for True vary; therefore it is recommended to set this parameter to False.
- di (bool) –
DeepInheritance flag: Include properties added by subclasses.
If None, this parameter will not be sent to the server, and the server default of True will be used.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
If None, this parameter will not be sent to the server, and the server default of True will be used.
Deprecated: Instance qualifiers have been deprecated in CIM. Clients cannot rely on qualifiers to be returned in this operation.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for properties.
If None, this parameter will not be sent to the server, and the server default of False will be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns: The instances, with their path attribute being a CIMInstanceName object with its attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: None, indicating the WBEM server is unspecified.
Return type: list of CIMInstance
- cn (string or CIMClassName) –
-
wbemcli.
gi
(ip, lo=None, iq=None, ico=None, pl=None)[source]¶ WBEM operation: GetInstance
Retrieve an instance.
Parameters: - ip (CIMInstanceName) –
Instance path.
If this object does not specify a namespace, the default namespace of the connection is used.
Its host attribute will be ignored.
- lo (bool) –
LocalOnly flag: Exclude inherited properties.
If None, this parameter will not be sent to the server, and the server default of True will be used.
Deprecated: Server implementations for True vary; therefore it is recommended to set this parameter to False.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
If None, this parameter will not be sent to the server, and the server default of False will be used.
Deprecated: Instance qualifiers have been deprecated in CIM. Clients cannot rely on qualifiers to be returned in this operation.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for properties.
If None, this parameter will not be sent to the server, and the server default of False will be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns: The instance, with its path attribute being a CIMInstanceName object with its attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: None, indicating the WBEM server is unspecified.
Return type: - ip (CIMInstanceName) –
-
wbemcli.
mi
(mi, iq=None, pl=None)[source]¶ WBEM operation: ModifyInstance
Modify the property values of an instance.
Parameters: - mi (CIMInstance) –
Modified instance, also indicating its instance path.
The properties defined in this object specify the new property values for the instance to be modified. Missing properties (relative to the class declaration) and properties provided with a value of None will be set to NULL.
- iq (bool) –
IncludeQualifiers flag: Modify instance qualifiers as specified in the instance.
If None, this parameter will not be sent to the server, and the server default of False will be used.
Deprecated: Instance qualifiers have been deprecated in CIM. Clients cannot rely on qualifiers to be modified in this operation.
- pl (iterable of string) – PropertyList: Names of properties to be modified (if not otherwise excluded). If None, all properties will be modified.
- mi (CIMInstance) –
-
wbemcli.
ci
(ni, ns=None)[source]¶ WBEM operation: CreateInstance
Create an instance in a namespace.
Parameters: - ni (CIMInstance) –
New instance.
Its classname attribute specifies the creation class. Its properties attribute specifies initial property values. Its path attribute is ignored, except for providing a default namespace.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace in the path attribute of the ni parameter, or to the default namespace of the connection.
Returns: The instance path, with its attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: None, indicating the WBEM server is unspecified.
Return type: - ni (CIMInstance) –
-
wbemcli.
di
(ip)[source]¶ WBEM operation: DeleteInstance
Delete an instance.
Parameters: ip (CIMInstanceName) – Instance path.
If this object does not specify a namespace, the default namespace of the connection is used. Its host attribute will be ignored.
-
wbemcli.
an
(op, ac=None, rc=None, r=None, rr=None)[source]¶ WBEM operation: AssociatorNames
Instance level use: Retrieve the instance paths of the instances associated to a source instance.
Class level use: Retrieve the class paths of the classes associated to a source class.
Parameters: - op (CIMClassName) – Source instance path; select instance level use.
- op – Source class path; select class level use.
- ac (string) –
AssociationClass filter: Include only traversals across this association class.
None means this filter is not applied.
- rc (string) –
ResultClass filter: Include only traversals to this associated (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- rr (string) –
ResultRole filter: Include only traversals to this role (= reference name) in associated (=result) objects.
None means this filter is not applied.
Returns: For instance level use, a list of CIMInstanceName objects representing the instance paths, with their attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
For class level use, a list of CIMClassName objects representing the class paths, with their attributes set as follows:
- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
Return type: list of CIMInstanceName or CIMClassName
-
wbemcli.
a
(op, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None)[source]¶ WBEM operation: Associators
Instance level use: Retrieve the instances associated to a source instance.
Class level use: Retrieve the classes associated to a source class.
Parameters: - op (CIMClassName) – Source instance path; select instance level use.
- op – Source class path; select class level use.
- ac (string) –
AssociationClass filter: Include only traversals across this assoiation class.
None means this filter is not applied.
- rc (string) –
ResultClass filter: Include only traversals to this associated (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- rr (string) –
ResultRole filter: Include only traversals to this role (= reference name) in associated (=result) objects.
None means this filter is not applied.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
Deprecated: Instance qualifiers have been deprecated in CIM.
None will cause the server default of False to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
Deprecated: Server impls. vary; Server may treat as False.
None will cause the server default of False to be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns: For instance level use, a list of CIMInstance objects representing the instances, with their path attribute being a CIMInstanceName object with its attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
For class level use, a list of tuple (classpath, class) representing the classes, with the following (unnamed) tuple items:
- classpath (CIMClassName): Class path with its attributes set as
follows:
- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- class (CIMClass): The representation of the class.
Return type: list of CIMInstance or tuple (CIMClassName, CIMClass)
-
wbemcli.
rn
(op, rc=None, r=None)[source]¶ WBEM operation: ReferenceNames
Instance level use: Retrieve the instance paths of the association instances referencing a source instance.
Class level use: Retrieve the class paths of the association classes referencing a source class.
Parameters: - op (CIMClassName) – Source instance path; select instance level use.
- op – Source class path; select class level use.
- rc (string) –
ResultClass filter: Include only traversals across this association (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
Returns: For instance level use, a list of CIMInstanceName objects representing the instance paths, with their attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
For class level use, a list of CIMClassName objects representing the class paths, with their attributes set as follows:
- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
Return type: list of CIMInstanceName or CIMClassName
-
wbemcli.
r
(op, rc=None, r=None, iq=None, ico=None, pl=None)[source]¶ WBEM operation: References
Instance level use: Retrieve the association instances referencing a source instance.
Class level use: Retrieve the association classes referencing a source class.
Parameters: - op (CIMClassName) – Source instance path; select instance level use.
- op – Source class path; select class level use.
- rc (string) –
ResultClass filter: Include only traversals across this association (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
Deprecated: Instance qualifiers have been deprecated in CIM.
None will cause the server default of False to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
Deprecated: Server impls. vary; Server may treat as False.
None will cause the server default of False to be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns: For instance level use, a list of CIMInstance objects representing the instances, with their path attribute being a CIMInstanceName object with its attributes set as follows:
- classname: Name of the creation class of the instance.
- keybindings: Keybindings of the instance.
- namespace: Name of the CIM namespace containing the instance.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
For class level use, a list of tuple (classpath, class) representing the classes, with the following (unnamed) tuple items:
- classpath (CIMClassName): Class path with its attributes set as
follows:
- classname: Name of the class.
- namespace: Name of the CIM namespace containing the class.
- host: Host and optionally port of the WBEM server containing the CIM namespace, or None if the server did not return host information.
- class (CIMClass): The representation of the class.
Return type: list of CIMInstance or tuple (CIMClassName, CIMClass)
-
wbemcli.
oei
(cn, ns=None, lo=None, di=None, iq=None, ico=None, pl=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenEnumerateInstances
Open an enumeration sequence to enumerate the instances of a class (including instances of its subclasses) in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - cn (string or CIMClassName) –
Name of the class to be enumerated (case independent).
If specified as a CIMClassName object, its host attribute will be ignored.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- lo (bool) –
LocalOnly flag: Exclude inherited properties.
Deprecated: Server impls for True vary; Set to False.
None will cause the server default of True to be used.
- di (bool) –
DeepInheritance flag: Include properties added by subclasses.
None will cause the server default of True to be used.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
Deprecated: Instance qualifiers have been deprecated in CIM.
None will cause the server default of False to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
Deprecated: Server may treat as False.
None will cause the server default of False to be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fi parameter.
None means that no such filtering is peformed.
- fq (string) –
Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.
None means that no such filtering is peformed.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - instances (list of CIMInstance):
The result set of instances in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
- cn (string or CIMClassName) –
-
wbemcli.
oeip
(cn, ns=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenEnumerateInstancePaths
Open an enumeration sequence to enumerate the instances of a class (including instances of its subclasses) in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - cn (string or CIMClassName) –
Name of the class to be enumerated (case independent).
If specified as a CIMClassName object, its host attribute will be ignored.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- lo (bool) –
LocalOnly flag: Exclude inherited properties.
Deprecated: Server impls for True vary; Set to False.
None will cause the server default of True to be used.
- fl (string) –
Filter query language to be used for the filter defined in the fi parameter.
None means that no such filtering is peformed.
- fq (string) –
Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.
None means that no such filtering is peformed.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - paths (list of CIMInstanceName):
The result set of instance paths in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
- cn (string or CIMClassName) –
-
wbemcli.
ori
(op, rc=None, r=None, iq=None, ico=None, pl=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenReferenceInstances
Open an enumeration sequence to enumerate the association instances of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - op (CIMInstanceName) – Source instance path.
- rc (string) –
ResultClass filter: Include only traversals across this association (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
Deprecated: Instance qualifiers have been deprecated in CIM.
None will cause the server default of False to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
Deprecated: Server impls. vary; Server may treat as False.
None will cause the server default of False to be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fi parameter.
None means that no such filtering is peformed.
- fq (string) –
Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.
None means that no such filtering is peformed.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - instances (list of CIMInstance):
The result set of instances in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
orip
(op, rc=None, r=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenReferenceInstancePaths
Open an enumeration sequence to enumerate the association instance paths of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - op (CIMInstanceName) – Source instance path.
- rc (string) –
ResultClass filter: Include only traversals across this association (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- fl (string) –
Filter query language to be used for the filter defined in the fi parameter.
None means that no such filtering is peformed.
- fq (string) –
Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.
None means that no such filtering is peformed.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - paths (list of CIMInstanceName):
The result set of instance paths in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
oai
(op, ac=None, rc=None, r=None, rr=None, iq=None, ico=None, pl=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenAssociatorInstances
Open an enumeration sequence to enumerate the associated instances of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - op (CIMInstanceName) – Source instance path.
- ac (string) –
AssociationClass filter: Include only traversals across this association class.
None means this filter is not applied.
- rc (string) –
ResultClass filter: Include only traversals to this associated (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- rr (string) –
ResultRole filter: Include only traversals to this role (= reference name) in associated (=result) objects.
None means this filter is not applied.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
Deprecated: Instance qualifiers have been deprecated in CIM.
None will cause the server default of False to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
Deprecated: Server impls. vary; Server may treat as False.
None will cause the server default of False to be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
- fl (string) –
Filter query language to be used for the filter defined in the fi parameter.
None means that no such filtering is peformed.
- fq (string) –
Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.
None means that no such filtering is peformed.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - instances (list of CIMInstance):
The result set of instances in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
oaip
(op, ac=None, rc=None, r=None, rr=None, fl=None, fq=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenAssociatorInstancePaths
Open an enumeration sequence to enumerate the associated instance paths of an instance in a namespace. Subsequent to this open response, additional instances may be pulled using the PullInstancesWithPath request. The enumeration sequence may also be closed before it is complete with the CloseEnumeration request.
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - op (CIMInstanceName) – Source instance path.
- rc (string) –
ResultClass filter: Include only traversals across this association (result) class.
None means this filter is not applied.
- r (string) –
Role filter: Include only traversals from this role (= reference name) in source object.
None means this filter is not applied.
- fl (string) –
Filter query language to be used for the filter defined in the fi parameter.
None means that no such filtering is peformed.
- fq (string) –
Filter to apply to objects to be returned. Based on filter query language defined by fl parameter.
None means that no such filtering is peformed.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - paths (list of CIMInstanceName):
The result set of instance paths in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
oqi
(ql, qi, ns=None, rc=None, ot=None, coe=None, moc=None)[source]¶ WBEM operation: OpenQueryInstances
Open an enumeration sequence to execute a query fi using the query language fl. If this operation returns eos == False, the PullInstances operation is used to request additional instances.
This operation returns a named tuple containing any instances returned and status of the enumeration sequence.
Parameters: - ql (string) – Filter query language to be used for the filter defined in the qi parameter. This must be a query language such as CQL or WQL but NOT FQL.
- qi (string) – Filter to apply to objects to be returned. Based on filter query language defined by the ql parameter.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the default namespace of the connection.
- rc (bool) –
Controls whether a result class definition describing the returned instances will be returned.
None will cause the server to use its default of False.
- ot (integer) –
Operation timeout in seconds. This is the minimum time the server must keep the enumerate session open between this open request and the next request.
A value of 0 indicates that the server should never time out.
The server may reject the proposed value.
None will cause the server to use its default timeout.
- coe (bool) –
Continue on error flag.
None will cause the server to use its default of False.
- moc (integer) –
Maximum number of objects to return for this operation.
None will cause the server to use its default of 0.
Returns: - instances (list of CIMInstance):
The result set of instances in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
- query_result_class (CIMClass):
Result class definition describing the returned instances, or None.
Return type: Named tuple, containing the following named items
-
wbemcli.
piwp
(ec, moc)[source]¶ WBEM operation: PullInstancesWithPath
Pull instances from the server as part of an already opened enumeration sequence. This operation can be used as the sequence continuation for OpenEnumerateInstancePaths, OpenAssociatorPaths and OpenReferencePaths.
Parameters: - ec (string) – Enumeration context from previous operation response for this enumeration session.
- moc (integer) – Maximum number of objects to return for this operation.
Returns: - instances (list of CIMInstance):
The result set of instances in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
pip
(ec, moc)[source]¶ WBEM operation: PullInstancePaths
Pull instance paths from the server as part of an already opened enumeration sequence. This operation can be used as the sequence continuation for OpenEnumeratePaths, OpenAssociatorPaths and OpenReferencePaths.
Parameters: - ec (string) – Enumeration context from previous operation response for this enumeration session.
- moc (integer) – Maximum number of objects to return for this operation.
Returns: - paths (list of CIMInstanceName):
The result set of instance paths in response to this request.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
pi
(ec, moc)[source]¶ WBEM operation: PullInstances
Pull instances from the server as part of an already opened enumeration sequence. This operation can be used as the sequence continuation for OpenQueryInstances.
Parameters: - ec (string) – Enumeration context from previous operation response for this enumeration session.
- moc (integer) – Maximum number of objects to return for this operation.
Returns: - instances (list of CIMInstance):
The result set of instances in response to this request. The path attribute is None.
- eos (bool):
True if this response is the complete response to this request and there are no more instances to return. Otherwise eos is False and the context item will define the context for the next operation.
- context (string):
A context string that must be supplied with any subsequent pull or close operation on this enumeration sequence.
Return type: Named tuple, containing the following named items
-
wbemcli.
ce
(ec)[source]¶ WBEM operation: CloseEnumeration
Close an existing open enumeration context early. Once the sequence is complete, the eos flag is set in the last response. Any time before this, the sequence may be closed early with this operation.
Parameters: ec (string) – Enumeration context from previous operation response for this enumeration session.
-
wbemcli.
im
(mn, op, *params, **kwparams)[source]¶ WBEM operation: InvokeMethod
Invoke a method on a target instance or a static method on a target class.
Parameters: - mn (string) – Method name.
- op (CIMClassName) – Target instance path.
- op – Target class path.
- *params (named args) – Input parameters for the method.
- **kwparams (keyword args) – Input parameters for the method.
Returns: Method return value, dict with output parameters.
Return type: tuple(rv, out)
-
wbemcli.
ecn
(ns=None, cn=None, di=None)[source]¶ WBEM operation: EnumerateClassNames
Enumerate the names of subclasses of a class, or of the top-level classes in a namespace.
Parameters: - ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- cn (string or CIMClassName) –
Name of the class whose subclasses are to be enumerated (case independent).
None will enumerate the top-level classes.
If specified as a CIMClassName object, its host attribute will be ignored.
- di (bool) –
DeepInheritance flag: Include also indirect subclasses.
None will cause the server default of False to be used.
Returns: The enumerated class names.
Return type: list of string
- ns (string) –
-
wbemcli.
ec
(ns=None, cn=None, di=None, lo=None, iq=None, ico=None)[source]¶ WBEM operation: EnumerateClasses
Enumerate the subclasses of a class, or the top-level classes in a namespace.
Parameters: - ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- cn (string or CIMClassName) –
Name of the class whose subclasses are to be enumerated (case independent).
None will enumerate the top-level classes.
If specified as a CIMClassName object, its host attribute will be ignored.
- di (bool) –
DeepInheritance flag: Include also indirect subclasses.
None will cause the server default of False to be used.
- lo (bool) –
LocalOnly flag: Exclude inherited properties.
None will cause the server default of True to be used.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
None will cause the server default of True to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
None will cause the server default of False to be used.
Returns: The enumerated classes.
Return type: list of CIMClass
- ns (string) –
-
wbemcli.
gc
(cn, ns=None, lo=None, iq=None, ico=None, pl=None)[source]¶ WBEM operation: GetClass
Retrieve a class.
Parameters: - cn (string or CIMClassName) –
Name of the class to be retrieved (case independent).
If specified as a CIMClassName object, its host attribute will be ignored.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- lo (bool) –
LocalOnly flag: Exclude inherited properties.
None will cause the server default of True to be used.
- iq (bool) –
IncludeQualifiers flag: Include qualifiers.
None will cause the server default of True to be used.
- ico (bool) –
IncludeClassOrigin flag: Include class origin info for props.
None will cause the server default of False to be used.
- pl (iterable of string) – PropertyList: Names of properties to be included (if not otherwise excluded). If None, all properties will be included.
Returns: The retrieved class.
Return type: - cn (string or CIMClassName) –
-
wbemcli.
cc
(nc, ns=None)[source]¶ WBEM operation: CreateClass
Create a class in a namespace.
Parameters:
-
wbemcli.
dc
(cn, ns=None)[source]¶ WBEM operation: DeleteClass
Delete a class.
Parameters: - cn (string or CIMClassName) –
Name of the class to be deleted (case independent).
If specified as a CIMClassName object, its host attribute will be ignored.
- ns (string) –
Name of the CIM namespace to be used (case independent).
If None, defaults to the namespace of the cn parameter if specified as a CIMClassName, or to the default namespace of the connection.
- cn (string or CIMClassName) –
-
wbemcli.
eq
(ns=None)[source]¶ WBEM operation: EnumerateQualifiers
Enumerate qualifier types (= declarations) in a namespace.
Parameters: ns (string) – Name of the CIM namespace to be used (case independent).
None will use the default namespace of the connection.
Returns: The enumerated qualifier types. Return type: list of CIMQualifierDeclaration
-
wbemcli.
gq
(qn, ns=None)[source]¶ WBEM operation: GetQualifier
Retrieve a qualifier type (= declaration).
Parameters: Returns: The retrieved qualifier type.
Return type:
-
wbemcli.
sq
(qd, ns=None)[source]¶ WBEM operation: SetQualifier
Create or modify a qualifier type (= declaration) in a namespace.
Parameters: - qd (CIMQualifierDeclaration) – Qualifier type.
- ns (string) –
Name of the CIM namespace to be used (case independent).
None will use the default namespace of the connection.
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¶
The development environment is pretty easy to set up.
Besides having a supported operating system with a supported Python version (see Supported environments), it is recommended that you set up a virtual Python environment.
Then, with a virtual Python environment active, clone the Git repo of this
project and prepare the development environment with make develop
:
$ git clone git@github.com:pywbem/pywbem.git
$ cd pywbem
$ make develop
This will install all prerequisites the package needs to run, as well as all prerequisites that you need for development.
Generally, this project uses Make to do things in the currently active
Python environment. The command make help
(or just make
) displays a
list of valid Make targets and a short description of what each target does.
Building the documentation¶
The ReadTheDocs (RTD) site is used to publish the documentation for the pywbem package at http://pywbem.readthedocs.io/
This page automatically gets updated whenever the master
branch of the
Git repo for this package changes.
In order to build the documentation locally from the Git work directory, issue:
$ make builddoc
The top-level document to open with a web browser will be
build_doc/html/docs/index.html
.
Testing¶
To run unit tests in the currently active Python environment, issue one of
these example variants of make test
:
$ make test # Run all unit tests
$ PYTHONPATH=. py.test testsuite/test_cim_obj.py -s # Run only this test source file
$ PYTHONPATH=. py.test InitCIMInstanceName -s # Run only this test class
$ PYTHONPATH=. py.test -k InitCIMInstanceName or Bla -s # py.test -k expressions are possible
Invoke py.test --help
for details on the expression syntax of its -k
option.
To run the unit tests and some more commands that verify the project is in good shape in all supported Python environments, use Tox:
$ tox # Run all tests on all supported Python versions
$ tox -e py27 # Run all tests on Python 2.7
Contributing¶
Third party contributions to this project are welcome!
In order to contribute, create a Git pull request, considering this:
- Test is required.
- Each commit should only contain one “logical” change.
- A “logical” change should be put into one commit, and not split over multiple commits.
- Large new features should be split into stages.
- The commit message should not only summarize what you have done, but explain why the change is useful.
- The commit message must follow the format explained below.
What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.
For further discussion of good and bad practices regarding commits, see:
Appendix¶
This section contains information that is referenced from other sections, and that does not really need to be read in sequence.
Special type names¶
This documentation uses a few special terms to refer to Python types:
- string
- a unicode string or a byte string
- unicode string
- a Unicode string type (
unicode
in Python 2, 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. - 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 type for callable objects (e.g. a function, calling a class returns a
new instance, instances are callable if they have a
__call__()
method). - DeprecationWarning
- a standard Python warning that indicates a deprecated functionality.
See section Deprecation policy and the standard Python module
warnings
for details. - Element
- class
xml.dom.minidom.Element
. Its methods are described in section Element Objects of 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.
Troubleshooting¶
Here are some trouble shooting hints for the installation of pywbem.
AttributeError for NullHandler during mkvirtualenv on Python 2.6¶
If the mkvirtualenv command fails on Python 2.6 with this error:
File "/usr/lib/python2.6/site-packages/stevedore/__init__.py", line 23,
in <module> LOG.addHandler(logging.NullHandler())
AttributeError: 'module' object has no attribute 'NullHandler'
then the stevedore PyPI package is too recent(!) The owners of that package spent effort to remove the previously existing Python 2.6 support in some steps, starting with stevedore v1.10.
The solution is to use stevedore v1.9. Note that for virtualenvwrapper to use it, it must be installed into the system Python:
$ sudo pip install stevedore==1.9
TypeError about StreamHandler argument ‘stream’ during mkvirtualenv on Python 2.6¶
If the mkvirtualenv command fails on Python 2.6 with this error:
File "/usr/lib/python2.6/site-packages/virtualenvwrapper/hook_loader.py",
line 101, in main
console = logging.StreamHandler(stream=sys.stderr)
TypeError: __init__() got an unexpected keyword argument 'stream'
then the virtualenvwrapper PyPI package is too old. As of its released version v4.7.1, a fix for that is in the master branch of its repository and has not been released yet.
While a new version of virtualenvwrapper with the fix is not yet released, a solution is to clone the virtualenvwrapper repository and to install it from its working directory. Note that it must be installed into the system Python:
$ git clone https://bitbucket.org/dhellmann/virtualenvwrapper.git virtualenvwrapper
$ cd virtualenvwrapper
$ sudo python setup.py install
Swig error ‘Unrecognized option -builtin’ during M2Crypto install¶
On Python 2.x, pywbem uses the M2Crypto package from PyPI and installs it during its own installation. The M2Crypto package invokes the Swig tool during its installation. If the version of Swig is too old, the invocation of Swig fails with:
swig error : Unrecognized option -builtin
The solution is to use Swig v2.0 or higher.
The pywbem setup script checks the version of Swig and installs a newer version of Swig, or if not available builds Swig from its sources (while automatically installing any further OS-level prerequisites needed for building Swig).
gcc does not find Python.h while installing M2Crypto¶
On Python 2.x, pywbem uses the M2Crypto package from PyPI and installs it during its own installation. The M2Crypto package invokes the Swig tool during its installation. Swig invokes the gcc compiler on source code it produces. That source code needs the Python.h header file.
If the invocation of gcc fails with:
SWIG/_m2crypto_wrap.c:127:20: fatal error: Python.h: No such file or directory
then you do not have the Python.h header file available.
The installation of pywbem with OS-level prereqs (see Installation) installs the necessary Python SDK package for C/C++ (or displays its package name). On RHEL, the missing package is python-dev.
Glossary¶
- dynamic indication filter
- dynamic filter
- An indication filter in a WBEM server whose life cycle is managed by a client. See DSP1054 for an authoritative definition and for details.
- static indication filter
- static filter
- An indication filter in a WBEM server that pre-exists and whose life cycle cannot be managed by a client. See DSP1054 for an authoritative definition and for details.
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
- DSP1033
- DMTF DSP1033, Profile Registration Profile, Version 1.1
- DSP1054
- DMTF DSP1054, Indications Profile, Version 1.2
- 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
Change log¶
This version of the documentation is development version 0.10.1 and contains the master branch up to this commit:
- Merge pull request #777 from pywbem/release_0.10.1 by Andreas Maier at 2017-09-27 23:18:07
Release v0.10.1
pywbem v0.10.1¶
Released: 2017-09-27
Incompatible changes¶
None
Enhancements¶
- Added support for automatically finding out whether for RHEL/CentOS/Fedora, the IUS version of the Python development packages should be used, dependent on whether the Python package is from IUS.
- Ensured that CIMDateTime objects for point in time values are timezone-aware when supplied with a timezone-naive datetime object. This does not change the behavior, but increases code clarity. Clarified that in the documentation of CIMDateTime. See issue #698.
Bug fixes¶
- Fix issue with MaxObjectCount on PullInstances and PullInstancePaths CIM_Operations.py methods. The MaxObjectCount was defined as a keyword parameter where it should have been be positional. This should NOT impact clients unless they did not supply the parameter at all so that the result was None which is illegal(Pull... operations MUST include MaxObjectCount). In that case, server should return error. Also extends these requests to test the Pull.. methods for valid MaxObjectCount and context parameters. See issue #656.
- Fixed TypeError “‘str’ does not support the buffer interface” during ‘setup.py develop’ on Python 3.x on Windows (issue #661).
- Fixed ValueError “underlying buffer has been detached” during ‘setup.py develop’ on Python 3.x on Windows (issue #661).
- Fixed names of Python development packages for SLES/OpenSUSE.
- Fixed that older versions of pip and setuptools failed or were rejected on some older Linux distros during make develop or make install, by upgrading them in these steps. See issues #759 and #760.
Build, test, quality¶
- Added Python 3.6 to the environments to be tested in Travis CI and Appveyor CI (issue #661).
- Added Python 2.6, 3.4 and 3.5 to the environments to be tested in Appveyor CI (issue #661).
- Fixed uninstall_pbr_on_py26.py to remove ‘pbr’ only if installed (issue #661).
- Fixed TypeError about dict ordering on Python 3.6 in unit test ‘test_nocasedict.TestOrdering’ (issue #661).
- Tolerated incorrect Unicode characters in output of commands invoked by
os_setup.py
(used for installation) that sometimes occurred on Windows (e.g. on the Appveyor CI with Python 3). - Pinned the version of the
wheel
package to <0.30.0 for Python 2.6, because wheel removed Python 2.6 support in its 0.30.0 version. - Improved the build process to ensure that half-built artefacts are removed before building (issue #754).
Documentation¶
- Documented that pywbem is not supported on Python 2.6 on Windows. and that 64-bit versions of Python are not supported on Windows.
pywbem v0.10.0¶
Released: 2016-12-20
Incompatible changes¶
- All methods of the WBEMSubscriptionManager class that returned instance paths (or lists thereof) in pywbem v0.9 now return the complete instances (or lists thereof) (pr #607).
- In wbemcli, removed the long global function names (e.g. EnumerateInstances), and kept the short names (e.g. ei) (issue #548).
Enhancements¶
Experimental: Added new methods to WBEMConnection to provide integrated APIs for the non-pull and pull operations, reducing the amount of code app writers must produce and providing a pythonic (generator based) interface for the methods that enumerate instances and instance paths, enumerator associators and references. These new methods have names in the pattern Iter<name of original function>. Thus, for example the new method IterEnumerateInstances creates a new API to integrate EnumerateInstances and the OpenEnumerateInstancesWithPath / PullInstancesWithPath. (issue #466).
Modified the XML parser to use SAX in place of minidom for operation response processing and indication processing. This is a significant reduction in memory usage (issue #498).
Declared the WBEM indications API and the WBEM server API to be final. These APIs had been introduced in v0.9.0 as experimental.
Added enter and exit methods to WBEMSubscriptionManager to enable using it as a context manager, whose exit method automatically cleans up by calling remove_all_servers() (issue #407).
Added methods to the operation recorder (class BaseOperationRecorder) for disabling and enabling it (issue #493).
The “Name” property of indication filters created via the WBEMSubscriptionManager class can now be controlled by the user (pr #607).
Indication filter, listener destination and indication subscription instances created via the WBEMSubscriptionManager class, that are “owned”, are now conditionally created, dependent on the owned instances that have been discovered upon restart of the WBEMSubscriptionManager (pr #607).
Modified operations that have a “PropertyList” attribute to allow the “PropertyList” attribute to have a single string in addition to the iterable. Previously this caused an XML error (issue #577).
Added an option -s / –script to wbemcli that supports executing scripts in the wbemcli shell.
Some example scripts are provided in the examples directory:
- wbemcli_server.py - Creates a WBEMServer object named SERVER representing a WBEM server.
- wbemcli_quit.py - Demo of terminating wbemcli from within a script.
- wbemcli_display_args.py - Demo of displaying input arguments.
- wbemcli_count_instances.py - Counts classes and instances in a server.
- wbemcli_clean_subscriptions.py - Removes all subscriptions, filters, and listener destination instances in a server.
- test_wbemcli_script.sh - A shell script that demos scripts.
Improved robustness and diagnostics in os_setup.py (issue #556).
Bug fixes¶
- Fixed the use of a variable before it was set in the remove_destinations() method of class WBEMSubscriptionManager.
- Fixed a compatibility issue relative to pywbem 0.7.0, where the pywbem.Error class was no longer available in the pywbem.cim_http namespace. It has been made available in that namespace again, for compatibility reasons. Note that using sub-namespaces of the pywbem namespace such as pywbem.cim_http has been deprecated in pywbem 0.8.0 (issue #511).
- Fixed an AttributeError in the remove_all_servers() method of WBEMSubscriptionManager and dictionary iteration errors in its remove_server() method (pr #583).
- Fixed a TypeError in the TestClientRecorder operation recorder that occurred while handling a ConnectionError (this recorder is used by the –yamlfile option of run_cim_operations.py) (issue #587).
- Fixed several errors in recorder on Python 3 (issue #531).
- In wbemcli, several fixes in the short global functions (issue #548).
- Fixed name of python devel package for Python 3.4 and 3.5.
- Several changes, fixes and improvements on WBEMSubscriptionManager (issues #462, #540, #618, #619).
- Added a check for unset URL target in recorder (issue #612).
- Fixed access to None in recorder (issue #621)
Build, test, quality¶
- Added flake8 as an additional lint tool. It is executed with make check. Fixed all flake8 issues (issues #512, #520, #523, #533, #542, #560, #567, #575).
- Changed names of the pylint and flake8 config files to match the default names defined for these utilities (pylintrc and .flak8) (issue #534).
- Added CIM Schema archive to the repository, in order to avoid repeated downloads during testing in the CI systems (issue #49).
- Added git as an OS-level dependency for development (it is used by GitPython when building the documentation) (pr #581).
- Added wheel as a Python dependency for development. This package is not installed by default in some Linux distributions such as CentOS 7, and when installing into the system Python this becomes an issue (pr #622).
- Added retry in setup script to handle xmlrpc failures when installing prerequisites from PyPI.
- Fixed logic errors in pycmp compatibility checking tool.
- Changed makefile to skip documentation build on Python 2.6 due to Sphinx having removed Python 2.6 support (issue #604).
- Fixed UnboundLocalError for exc in setup.py (issue #545).
- Added an executable run_enum_performance.py to the testsuite to test pull performance. It generates a table of the relative performance of EnumerateInstances vs. OpenEnumerateInstances / PullInstancesWithPath performance over a range of MaxObjectCount, response instance sizes, and total number of instances in the response.
- Completed the test_client.py mock tests for all instance operations.
- Improved the tests in run_cim_operations.py.
Documentation¶
- Added the global functions available in the wbemcli shell to the documentation (issue #602).
- Improved usage information for the “Tutorial” section, to make usage of Jupyter tutorials more obvious (issue #470).
- Added “Installation” and “Development” sections to the documentation, and moved some content from the “Introduction” section into a new “Appendix” section. Added an installation trouble shooting section to the appendix (pr #509).
- Added a section “Prerequisite operating system packages” to the documentation that describes the prerequisite packages by distribution (pr #549).
- Fixed a documentation build error on Python 2.6, by pinning the GitPython version to <=2.0.8, due to its use of unittest.case which is not available on Python 2.6 (issue #550).
- Clarified the behavior for the default WBEMConnection timeout (None) (issue #628).
- Fixed a documentation issue where the description of CIMError was not clear that the exception object itself can be accessed by index and slice (issue #511).
- Added the wbemcli global functions to the documentation (issue #608).
pywbem v0.9.0¶
Released: 2016-09-06
Deprecations¶
- Deprecated the use of the value instance variable and ctor parameter of the CIMParameter class, because that class represents CIM parameter declarations, which do not have a default value. Accessing this instance variable and specifying an initial value other than None now causes a DeprecationWarning to be issued.
- Deprecated ordering comparisons for NocaseDict, CIMInstance, CIMInstanceName, and CIMClass objects. This affects the ordering comparisons between two such objects, not the ordering of the items within such a dictionary. Use of ordering operators on objects of these classes now causes a DeprecationWarning to be issued.
- Deprecated the methodname input argument of CIMMethod(), and renamed it to name. methodname still works but its use causes a DeprecationWarning to be issued.
- Deprecated the use of the verify_callback parameter of WBEMConnection. because it is not used with the Python ssl module and will probably be removed completely in the future. Its use now causes a DeprecationWarning to be issued. (Issue #297)
Known Issues¶
- Installing PyWBEM on Python 2.6 has a conflict with the pbr package from PyPI, resulting in a TypeError: “dist must be a Distribution instance”. This issue is specific to Python 2.6 and does not occur in any of the other supported Python versions (2.7, 3.4, 3.5). This issue can be mitigated by uninstalling the pbr package, or if that is not possible, by migrating to Python 2.7. See issue #26 on GitHub.
- MOF using names that are reserved keywords will fail to compile in the MOF compiler. For example, a CIM property named ‘indication’. See issue #62 on GitHub.
Clean Code¶
- Moved the following unused modules from the pywbem package directory
into a new attic directory, in order to clean up the pywbem
package:
- cim_provider.py
- cim_provider2.py
- cimxml_parse.py
- test_cimxml_parse.py
- twisted_client.py
- Moved the script-related portions of the pywbem/mof_compiler.py module into the mof_compiler script.
- Moved the complete pywbem/wbemcli.py module into the wbemcli script.
- Removed half-baked code for HTTP proxy/tunneling support.
Enhancements¶
Implemented pull operations per DMTF specification DSP0200 and DSP0201. This includes the following new client operations to execute enumeration sequences:
- OpenEnumerateInstances
- OpenEnumerateInstancePaths
- OpenAssociatorInstances
- OpenAssociatorInstancePaths
- OpenReferenceInstances
- OpenReferenceInstancePaths
- OpenQueryInstances
- PullInstances
- PullInstancesWithPath
- PullInstancePaths
- CloseEnumeration
The EnumerationCount operation is NOT implemented, because it is both deprecated and unusable. (Issue #9)
Unit tests of the pull operations are included and mock tests are written for at least some parts of the pull operations.
Implemented support for reading information from WBEM servers according to the DMTF WBEM Server Profile (DSP1071) and DMTF Profile Registration Profile (DSP1033) with a new WBEMServer class. Note that not everyhting in these profiles needs to be implemented in the WBEM server for this to work:
- The WBEMServer class is a client’s view on a WBEM server and provides consistent and convenient access to the common elements of the server, including namespace names, interop namespace name, registered profile information, server branding, and central/scoping class algorithms.
- Added unit tests for this new class in run_cim_operations.py and test_client.py.
- Added a demo of the discovery abilities of the WBEMServer class in the examples/explore.py script.
Experimental - This new class is experimental for pywbem version 0.9.0 because this is the initial release of a significant change and subject to changes to the API.
(Issues #9, #346, #468)
Implemented support for WBEM subscription management and a WBEM indication listener:
- Added a WBEMListener class that allows the creation of a listener entity to receive indications.
- Added a WBEMSubscriptionManager class that allows management of indication subscriptions, indication filters, and listener destination instances on the WBEM Server using the new WBEMServer class.
- Added unit tests for these new classes and extended other existing tests accordingly, e.g. run_cim_operations.py.
Experimental - These new classes are experimental for pywbem version 0.9.0 because this is the initial release of a significant change and subject to changes to the API.
(Issues #66, #421, #414, #379, #378)
The distribution formats released to PyPI have been extended. There are now:
- Source archive (existed)
- Universal wheel (new)
(Issue #242)
Starting with v0.9.0, pywbem no longer stores the distribution archives in the repository, because the process for releasing to PyPI creates new distribution archives instead of using the created ones. This makes it difficult to ensure that the archives stored in the repository are the same.
Upgraded M2Crypto to use official 0.24.0 from PyPI.
Added check for minimum Python version 3.4 when running on Python 3. That requirement was already documented, now it is also enforced in the code.
Migrated API documentation to Sphinx.
Improved documentation of many classes of the external API.
Replaced [] and {} default arguments with None.
Changed the return value of repr() for WBEMConnection, CIM type classes (e.g. Sint8, CIMDateTime), and CIM object classes (e.g. CIMInstance) so that they now return all attributes in a reasonable order, and are suitable for debugging.
Clarified in the description of CIMClassName.__str__() and CIMInstanceName.__str__() that they return the WBEM URI representation of the class path and instance path.
Changed the return value of str() for CIM object classes (e.g. CIMProperty) so that they now return a short set of the most important attributes for human consumption. Specifically, this resulted in the following changes:
- For CIMProperty, reduced the complete set of attributes to a short set.
- For CIMQualifierDeclaration, added the attribute value.
Changes in the CIMError exception class:
- Changed the behavior of the __str__() method to return a human readable string containing the symbolic name of the status code, and the status description. The previous behavior was to return a Python representation of the tuple status code, status description.
- Added properties status_code (numeric CIM status code), status_code_name (symbolic name of CIM status code), and status_description (CIM status description).
- Updated the documentation to no longer show the unused third tuple element exception_obj. It was never created, so this is only a doc change.
Added CIM status codes 20 to 28, specifically to support the pull operations.
Changed the ParseError exception to be derived from the Error base exception, so that now all pywbem specific exceptions are derived from Error.
Added tocimxmlstr() as a global function and as methods on all CIM object classes. It returns the CIM-XML representation of the object as a unicode string either in a single-line variant, or in a prettified multi-line variant.
Created tomof() for CIMProperty making common functionality available to both class and instance tomof() (PR #151)
Added an optional namespace parameter to the WBEMConnection.CreateInstance() method, for consistency with other methods, and to have an explicit alternative to the namespace in the path component of the NewInstance parameter.
The ClassName parameter of several operation methods can be specified as both a string and a CIMClassName object. In the latter case, a namespace in that object was ignored so far. Now, it is honored. This affects the following WBEMConnection methods: EnumerateInstanceNames, EnumerateInstances, EnumerateClassNames, EnumerateClasses, GetClass, DeleteClass.
Enhanced the CIM integer data types (e.g. pywbem.Uint8()) to accept all input parameters that are supported by int().
Added the concept of a valid value range for the CIM integer data types, that is enforced at construction time. For compatibility, this strict checking can be turned off via a config variable: pywbem.config.ENFORCE_INTEGER_RANGE = False.
Extended wbemcli arguments to include all possible arguments that would be logical for a ssl or non-ssl client. This included arguments for ca certificates, client keys and certificates, timeout. It also modifies the server argument to use http:// or https:// prefix and suffix with :<port number> and drops the old arguments of –port and –no-ssl
Improved Swig installation code by reinstalling Swig if it was installed but still cannot be found in PATH (e.g. if the installation was tampered with).
Removed dependency on git (this was a leftover from when M2Crypto needed to be obtained from its development repo).
Added debug prints for two probably legitimate situations where socket errors are ignored when the server closes or resets the connection. These debug prints can be enabled via the debug instance variable of the WBEMConnection object; they are targeted at development for investigating these situations.
Extended run_cim_operations.py which is a live test against a server. It has only been tested against OpenPegasus but was extended to cover more details on more of the operation types and to create a test subclass to specifically test against OpenPegasus if OpenPegasus is detected as the server.
Added description of supported authentication types in WBEM client API.
Allowed tuple as input for PropertyList parameter of WBEMConnection operation methods. Documentation indicated that iterable was allowed but was limited to list. (Issue #347)
Added a tutorial section to the generated documentation, using Jupyter Notebooks for each tutorial page. (Issue #324)
Added the concept of operation recording on WBEM connections, that supports user-written operation recorders e.g. for tracing purposes. Added an operation recorder that generates test cases for the test_client unit test module. (Issue #351)
Extended wbemcli for all pull operations. (Issue #341)
Changed command line options of mof_compiler command to be consistent with wbemcli, and added support for specifying certificate related options. use of the old options is checked and causes an according error message to be displayed. Note, this is an incompatible change in the command line options. (Issue #216)
Cleaned up exception handling in WBEMConnection methods: Authentication errors are now always raised as pywbem.AuthError (OpenWBEM raised pywbem.ConnectionError in one case), and any other bad HTTP responses are now raised as a new exception pywbem.HTTPError.
Clarified MofParseError by defining attributes as part of the class init and moving some code from productions to the class itself (Issue #169). This makes the MofParseError exception more suitable for use from the productions themselves. The original definition was really only for use as a call from ply. Add tests for invalid qualifier flavors to unit tests and add test in mof_compiler.py for conflicting flavors ex. tosubclass and restricted in the same definition. This test uses the new MofParseError. (Issue #204)
Extended PropertyList argument in request operations to be either list or tuple. (Issue #347)
Added support for representing control characters in MOF strings using MOF escape sequences, e.g. U+0001 becomes “x0001”.
Modified qualifier MOF output to stay within 80 column limits. (Issue #35)
Bug fixes¶
- Fixed KeyError when iterating over CIMInstance and CIMInstanceName objects.
- Fixed bug that MOF escape sequences in strings were passed through unchanged, into generated MOF, by removing needless special-casing code.
- Fixed bug with class MOF generation where output was not including array indicator ([]). (Issue #233)
- Moved class property MOF output processing to CIMProperty and fixed issue where default values were not being generated. (Issues #223 and #231)
- Fixed bug in method MOF output where array flag “[]” was left off array parameters.
- In the WBEMConnection.ModifyInstance() method, the class names in the instance and path component of the ModifiedInstance parameter are required, but that was neither described nor checked. It is now described and checked.
- In the WBEMConnection.ModifyInstance() method, a host that was specified in the path component of the ModifiedInstance parameter incorrectly caused an INSTANCEPATH element to be created in the CIM-XML. This bug was fixed, and a host is now ignored.
- Fixed a bug where the CIM datetime string returned by the str() function on CIMDateTime interval objects contained incorrect values for the minutes and seconds fields on Python 3. (Issue #275).
- Fixed an IndexError in cim_http.wbem_request() that occurred during handling of another exception.
- Fixed issue with Python 3 and https that was causing connect() to fail. This completely separates connect() code for Python 3 ssl module from Python 2 M2Crypto.
- Fixed problem that wbemcli in Python 3 when used without existing history file would fail with “TypeError: ‘FileNotFoundError’ object is not subscriptable”. (Issue #302)
- Fixed issue with tomof() output where datetime values were not quoted. (Issue #289)
- Eliminated automatic setting of toinstance flavor in mof_compiler when tosubclass is set. Also enabled use of toinstance flavor if defined in a class or qualifier declaration. (Issue #193)
- Fixed problem in class-level associator operations that namespace was classname when classname was passed as a string. (Issue #322)
- Fixed hole in checking where class CIMMethod allowed None as a return_type. (Issue #264)
- Fixed a documentation issue with associators/references return types. It was documented as a list of classes for class level return, but it actually is a list of tuples of classname, class. (Issue #339)
- Created a common function for setting SSL defaults and tried to create the same level of defaults for both Python2 (M2Crypto) and Python 3 (SSL module). The minimum level protocol set by the client is TLSV1 now whereas in previous versions of pywbem it was SSLV23. (Issue #295)
- Fixed issue where mof_compiler was setting values for compile of instances into the class object and also setting the values for the last compiled instance in a compile unit into all other compiled instances for the same class. Since the concept of compiling a path into compiled instances is flawed (there is no requirement to include all properties into a instance to compile that code was removed so that the path is NOT build into a compiled instance. Finally the qualifiers from the class were also included in compiled instances which was incorrect and an accident of the code. They are no longer included into the compiled instances.) (Issue #402)
- Fixed description in INSTALL.md to correctly describe how to establish OS-level prerequisites.
- Cleaned up the timeouts on SSL and created specific tests for timeouts against a live server. (Issues #363, #364)
pywbem v0.8.4¶
Released: 2016-05-13
Bug fixes¶
- Fixed an IndexError in cim_http.wbem_request() that occurred during handling of another exception.
- Fixed problem that wbemcli in Python 3 when used without existing history file would fail with “TypeError: ‘FileNotFoundError’ object is not subscriptable” (issue #302).
- Fixed issues with Python 3 and HTTPS that were causing the connecttion to fail. This completely separates the connect() code for Python 3 (using the Python SSL module) from the code for Python 2 (using M2Crypto) (issues #150, #273, #274, #288).
Enhancements¶
- Improved description in INSTALL.md to better describe how to establish OS-level prerequisites.
- Improved Swig installation code by reinstalling Swig if it was installed but still cannot be found in PATH (e.g. if the installation was tampered with).
- Removed dependency on git (this was a leftover from when M2Crypto needed to be obtained from its development repo).
- Added debug prints for two probably legitimate situations where socket errors are ignored when the server closes or resets the connection. These debug prints can be enabled via the debug instance variable of the WBEMConnection object; they are targeted at development for investigating these situations.
- Added check for minimum Python version 3.4 when running on Python 3. That requirement was already documented, now it is also enforced in the code.
- Enhanced the wbemcli script with options supporting certificates. For details, invoke with –help, or look at the online documentation. NOTE: The –no-ssl and –port options have been removed. Specify the protocol and port number in the server URL.
Clean code¶
- Removed half-baked code for HTTP proxy/tunneling support.
pywbem v0.8.3¶
Released: 2016-04-15
Bug fixes¶
- To address some M2Crypto issues, upgraded to use M2Crypto >=0.24 from PyPI.
- For Windows, using M2CryptoWin32/64 >=0.21 from PyPI, in order to avoid the Swig-based build in Windows.
- Improved the mechanism to build the LEX/YACC table modules, so that import errors for freshly installed packages (e.g. M2Crypto) no longer occur.
Enhancements¶
- Added Windows versions of WBEM utility commands: wbemcli.bat, mof_compiler.bat.
pywbem v0.8.2¶
Released: 2016-03-20
Bug Fixes¶
- Eliminated dependency on six package during installation of pywbem. (Andreas Maier)
Dependencies¶
- v0.8.x has the following dependencies on other PyPI packages
(see install_requires argument in setup script):
- M2Crypto
- ply
- six
pywbem v0.8.1¶
Released: 2016-03-18
Known Issues¶
- Installing PyWBEM on Python 2.6 has a conflict with the pbr package from PyPI, resulting in a TypeError: “dist must be a Distribution instance”. This issue is specific to Python 2.6 and does not occur in any of the other supported Python versions (2.7, 3.4, 3.5). This issue can be mitigated by uninstalling the pbr package, or if that is not possible, by migrating to Python 2.7. See issue #26 on GitHub.
- MOF using names that are reserved keywords will fail to compile in the MOF compiler. For example, a CIM property named ‘indication’. See issue #62 on GitHub.
- The Pulled Enumeration Operations introduced in DSP0200 1.3 are not supported in this release. See issue #9 on GitHub.
- Note that some components of this PyWBEM Client package are still
considered experimental:
- The twisted client module twisted_client.py.
- The Python provider modules cim_provider.py and cim_provider2.py.
- The CIM indication listener in the irecv directory. See issue #66 on GitHub.
Changes¶
- The MOF compiler is now available as the command ‘mof_compiler’ that gets installed into the Python script directory. It is now separate from the ‘mof_compiler’ module within the ‘pywbem’ package. In 0.7.0, the module was at the same time the script. (Andreas Maier)
- The WBEM client CLI is now available as the command ‘wbemcli’ that gets installed into the Python script directory. It is now separate from the ‘wbemcli’ module within the ‘pywbem’ package. In 0.7.0, the module was at the same time the script. (Andreas Maier)
- In 0.7.0, most symbols defined in the sub-modules of the ‘pywbem’ package were folded into the ‘pywbem’ package namespace, cluttering it significantly. The symbols in the ‘pywbem’ package namespace have been reduced to a well-defined set that is now declared the external API of the WBEM client library, and is supposed to be sufficient. If you find that you need something you were used to, please think twice as to whether that makes sense to be part of the external PyWBEM API, and if so, let us know by opening an issue.
- Since 0.7.0, some exceptions that can be raised at the external API of the WBEM client library have been cleaned up.
Enhancements¶
- Verify certificates against platform provided CA trust store in /etc/pki/tls/certs. Linux only. (Peter Hatina)
- Added ‘-d’ option to MOF compiler that causes the compiler to perform a dry-run and just check the MOF file syntax. This allows to more easily detect included MOF files when used together with the ‘-v’ option. (Jan Safranek)
- Added support for non-ASCII (Unicode) characters. (Michal Minar, Andreas Maier)
- Improved information in the message text of some exceptions (TypeError and KeyError in cim_obj.py, ValueError in cim_obj.py, and ParseError in tupleparse.py). (Andreas Maier)
- Moved the definition of the pywbem version from setup.py to __init__.py, in order to make it available to programs using pywbem as pywbem.__version__. (Andreas Maier)
- Added support for direct iteration over NocaseDict objects using for and in by adding __iter__(), e.g. for use with CIMInstance.properties. (Andreas Maier)
- Added more instance attributes to be shown in repr() on CIMProperty and other classes in cim_obj. (Andreas Maier)
- Added and improved docstring-based documentation in the pywbem modules cim_operations, cim_http, cim_obj, cim_types, and the pywbem module. (Andreas Maier)
- Improved the way missing file:// URL support on Windows is handled, by now issuing a proper error message instead of stumbling across the missing socket.AF_UNIX constant. (Andreas Maier)
- Improved the way missing OWLocal authorization with the OpenWBEM server is handled on Windows, by now issuing a proper error message instead of stumbling across the missing os.getuid() function. (Andreas Maier)
- Improved Windows portability by no longer attempting to import pwd in case the userid is not set in the environment variables that are checked when the WBEM server is local. (Andreas Maier)
- Added support for ExecQuery operation to twisted client. (Robert Booth)
- Added get() methods on CIMInstance and CIMInstanceName to step up to the statement that they behave like dictionaries w.r.t. properties and key bindings. (Andreas Maier)
- Improved help text of test_cim_operations.py test program. (Andreas Maier)
- Added an optional Params argument to InvokeMethod(), that is an ordered list of CIM input parameters, that preserves its order in the CIM-XML request message. This is to accomodate deficient WBEM servers that do not tolerate arbitrary order of method input parameters as required by the standard. The new argument is optional, making this a backwards compatible change of InvokeMethod(). (Andreas Maier)
- Cleaned up the public symbols of each module by making symbols private that are used only internally. Specifically, the following symbols have been made private: In cimxml_parse: _get_required_attribute, _get_attribute, _get_end_event, _is_start, _is_end. In cim_xml: _text (was: Text). (Andreas Maier)
- Cleaned up symbols imported by wildcard import by defining __all__ in each module with only the public symbols defined in that module (removing any symbols imported into the module), except for the following modules which define less than the complete set of public symbols in their __all__: mof_compiler, twisted_client, tupleparse, cimxml_parse, cim_http. (Andreas Maier)
- Added support for using CDATA section based escaping in any requests sent to the WBEM server. The default is still XML entity reference based escaping, the CDATA based escaping can be turned on by setting the switch _CDATA_ESCAPING accordingly, which is a global variable in the cim_xml module. (Andreas Maier)
- Simplified the exceptions that can be raised by WBEMConnection methods, and improved the information in the exception messages. See description of WBEMConnection class for details. (Andreas Maier)
- Added support for timeouts to WBEMConnection, via a new timeout argument, that defaults to no timeout. (This finally increased the minimum version of Python to 2.6. (Andreas Maier)
- Improved installation process of PyWBEM, particularly related to M2Crypto. (Andreas Maier)
- Added support for Python 3. Issue #3 on GitHub. (Ross Peoples, Andreas Maier)
Bug Fixes¶
- Fix syntax error in CIM DTDVERSION error path. Allow KEYVALUE VALUETYPE attribute to be optional as specified in the DTD. (Andreas Linke)
- Added parsing of InvokeMethod return value and output parameters for Twisted Python client. (Tim Potter)
- Fixed cim_provider2.py to properly support shutdown() and can_unload() (called from CMPI cleanup() functions). Support was recently added to cmpi-bindings for this. (Bart Whiteley)
- Fixed XML parsing to accept SFCB-style embedded instance parameters. (Mihai Ibanescu)
- Use getpass module instead of pwd to detect local user to fix Win32. (Tim Potter)
- Re-throw KeyError exceptions with capitalised key string instead of lower cased version in NocaseDict.__getitem__(). (Tim Potter)
- Use base64.b64encode() instead of base64.encodestring() in Twisted client. (Mihai Ibanescu)
- Fix missing CIMDateTime import in Twisted client. (Mihai Ibanescu)
- Fixed CIMInstanceName rendering to string. It is now possible to pass the rendered string value as an instance path argument of a CIM method. (Jan Safranek, Michal Minar)
- For Python providers, fixed the comparsion of the Role parameter in association operations to be case insensitive, and removed an erroneous test that raised an exception when the property specified in the Role parameter was not also in the property list specified by the Properties parameter. (Jan Safranek)
- For Python providers, converted debug ‘print’ statements to trace messages that end up in the system log. (Jan Safranek)
- The CIM-XML parser no longer throws an exception when parsing a qualifier declaration. Note: The CIM-XML supported by this fix does not conform to DSP0201 so far. Further fixes are pending. (Jan Safranek)
- Fixed parsing errors for connection URLs with IPv6 addresses, including zone indexes (aka scope IDs). (Peter Hatina, Andreas Maier)
- Fixed the hard coded socket addressing family used for HTTPS that was incorrect in some IPv6 cases, by determining it dynamically. (Peter Hatina)
- Fixed the list of output parameters of extrinsic method calls to be returned as a case insensitive dictionary (using cim_obj.NocaseDict). (Jan Safranek)
- Fixed the checking of CIMVERSION attributes in CIM-XML to only verify the major version, consistent with DSP0201 (see subclause 5.2.1, in DSP0201 version 2.3.1). (Jan Safranek)
- Fixed error in cim_http.py related to stronger type checking of Python 2.7. (Eduardo de Barros Lima)
- Removed erroneous qualifier scopes SCHEMA and QUALIFIER from the MOF compiler (see DSP0004). (Andreas Maier)
- Fixed debug logging of CIM-XML payload (that is, conn.last_*request/reply attributes) for extrinsic method calls, to now be consistent with intrinsic method calls. (Andreas Maier)
- Fixed TOCTOU (time-of-check-time-of-use) error when validating peer’s certificate. (Michal Minar)
- Added a check in the CIMInstanceName constructor that the classname argument is not None. (Andreas Maier)
- Fixed the issue in the CIMProperty constructor that specifying a tuple for the value argument was incorrectly detected to be a scalar (and not an array). (Andreas Maier)
- Fixed the issue in the CIMProperty constructor that specifying a datetime or timedelta typed value resulted in storing the provided object in the value attribute, instead of converting it to a CIMDateTime object. (Andreas Maier)
- Fixed the issue in the CIMProperty constructor that specifying a datetime formatted string typed value argument along with type=’datetime’ resulted in storing the provided string object in the value attribute, instead of converting it to a CIMDateTime object. (Andreas Maier)
- Fixed several cases in the CIMProperty constructor of unnecessarily requiring the optional arguments type, is_array, embedded_object, or reference_class. These optional arguments are now only necessary to be provided if they cannot be implied from provided arguments (mainly from value). (Andreas Maier)
- Fixed the issue in the CIMProperty constructor that an embedded_object argument value of ‘object’ was changed to ‘instance’ when a CIMInstance typed value argument was also provided. (Andreas Maier)
- Fixed the issue in the CIMProperty constructor that the first array element was used for defaulting the type attribute, without checking that for None, causing an exception to be raised in this case. (Andreas Maier)
- Added a check in the CIMProperty constructor that the name argument is not None. (Andreas Maier)
- Fixed the issue that the CIMProperty constructor raised only TypeError even when the issue was not about types; it now raises in addition ValueError. (Andreas Maier)
- Changed the exception that is raised in NocaseDict.__setitem__() for invalid key types, to be TypeError in instead of KeyError. Updated the testcases accordingly. (Andreas Maier)
- Added checks for more than one argument and for unsupported argument types to the constructor of NocaseDict. (Andreas Maier)
- Fixed incorrectly labeled namespace variables in twisted client. (Robert Booth)
- Fixed that WBEMConnection.last_raw_reply was not set to the current reply in case of parsing errors in the reply. (Andreas Maier)
- Reintroduced Python 2.6 support in cim_http.HTTPSConnection.connect()
that disappeared in early drafts of this version: (Andreas Maier)
- Removed SSLTimeoutError from except list; being a subclass of SSLError, it is catched via SSLError.
- Invoked socket.create_connection() without source_address, if running on Python 2.6.
- Fixed bug where HTTP body was attempted ot be read when CIMError header is set, causing a hang. (Andreas Maier)
- Added CIM-XML declaration support for alternative PyWBEM client based on twisted. (Andreas Maier)
- Added support for Windows to wbemcli.py, by making dependency on HOME environment variable optional, and adding HOMEPATH environment variable. Also, cleaned up the global namespace of wbemcli.py and made it importable as a module. (Andreas Maier)
- Fixed errors in generated MOF (e.g. in any tomof() methods): (Andreas Maier)
- Missing backslash escaping within string literals for n, r, t, “.
- Representation of REF types was incorrect.
- ‘=’ in array-typed qualifier declarations was missing.
- Fixed size indicator was missing in array elements.
- Qualifiers of method parameters were missing.
- Improvements in generated MOF: (Andreas Maier)
- Changed order of qualifiers to be sorted by qualifier name.
- Added empty line before each property and method in the class for better readability.
- Method parameters are now placed on separate lines.
- Moved generation of method qualifiers from class into method. This changes the behavior of CIMMethod.tomof() to now generate the method qualifiers.
- Fixed error where invoking mof_compiler.py with a file based URL that did not start with ‘file:’ failed with an undefined variable url_ in cim_http.py. Issue #1 on GitHub. (Klaus Kaempf, Andreas Maier)
- Fixed build error that raised a YaccError in mof_compiler.py: “Syntax error. Expected ‘:’”. Issue #2 on GitHub. (Andreas Maier)
- Fixed issue where MOF compiler did not find include files with a path specified. Issue #4 on GitHub. (Karl Schopmeyer)
- Added missing LocalOnly parameter to EnumerateInstances() of the wbemcli script. Issue #33 on GitHub. (Karl Schopmeyer)
- Added workaround for Python 2.6 for Python issue 15881.
- Removed the lex.py and yacc.py files from PyWBEM, and used them from the ply package, which is their real home. This fixes a number of issues because the latest version is now used. Issue #8 on GitHub.i (Karl Schopmeyer)
- Fixed the issue that the LEX and YACC table modules were regenerated under certain conditions. Issue #55 on GitHub. (Karl Schopmeyer)
- Fixed bugs in the mof_compiler script. (Karl Schopmeyer)
- Fixed errors in the description of the qualifier operations in WBEMConnection. Issue #91 on GitHub. (Andreas Maier)
Testing¶
- Added support for running the unit test cases without having to be in the testsuite directory. This was done by setting up the DTD_FILE path correctly for any XML tests. (Andreas Maier)
- Improved the quality of assertion messages issued when testcases fail, to include context information and types. (Andreas Maier)
- Added docstrings to test cases. (Andreas Maier)
- Added testcases for CIMProperty.__init__() to be comprehensive. (Andreas Maier)
- In XML validation tests, added the expected XML root element. (Andreas Maier)
- Added a header to any error messages issued by xmllint. (Andreas Maier)
- Fix: Merged stderr into stdout for the xmllint invocation, xmllint error messages go to stderr and had been dropped before. (Andreas Maier)
- Fix: The “mkdir -p ..:” command in the comfychair testcase constructor created subdirectories named “-p” when running on Windows; replaced that command with os.makedirs(). (Andreas Maier)
- Fix: Replaced the “rm -fr ...” command in the comfychair testcase constructor with shutil.rmtree(), in order to better run on Windows. (Andreas Maier)
- Fix: In comfychair._enter_rundir(), moved registration of cleanup function _restore_directory() to the end, so cleanup happens only if no errors happened. (Andreas Maier)
- Fixed a bug in pywbem/trunk/testsuite/test_tupleparse.py in function ParseCIMProperty.runtest(), where the use of real tab characters caused a few lines to be incorrectly indented, and as a result, ignored for the test. (Andreas Maier)
- Improved Windows portability in testsuite: Moved from using the Unix-only functions posix.WIFSIGNALED() and posix.WEXITSTATUS() for testing the success of subprocess.wait(), to simply testing for 0. (Andreas Maier)
- Added ability to invoke test_cim_operations.py with comfychair arguments, and added printing of exception information if an operation fails. (Andreas Maier)
- Migrated from comfychair to py.test, standard Python unittest, and to tox. (Andreas Maier)
- Added test_client.py with a few initial testcases. This is an end-to-end test concept that allows specifying test cases that cover the entire PyWBEM Client top to bottom. It mocks the socket layer and allows specifying the test cases in YAML, starting with input at the PyWBEM Client API (e.g. an operation and its parameters), the expected CIM-XML request at the socket payload level resulting from this input (the request is verified), the CIM-XML response that is to be generated, and finally an expected result at the PyWBEM Client API that is being verified. (Andreas Maier)
- Added use of Travis CI test environment. Commits to GitHub now trigger test runs on the Travis CI. A badge on the GitHub README page shows the current test result of the master branch, and links to the Travis site for the test results of the branches of any pull requests. (Andreas Maier)
- Added support for reporting test coverage, using the Python ‘coverage’ package. Coverage is reported on stdout as part of testing, e.g. with ‘make test’ for the current Python environment, or with ‘tox’ for all supported Python environments. (Andreas Maier)
- Added multiple tests for client connection timeout. A mock test was added for both HTTP and HTTPs. However, this causes an error in python 2 with HTTPS so two new options were added to test_client.py. First, a new parameter ignore_python_version was added to the yaml to define a major version of python for which a particulare testcase would be ignored. Second a non-documente option was added to test_client.py to execute a single testcase if the name of that testcase is the only parameter on the test_client.py cmd line. Finally a whole new run_operationtimeout.py file was added to testsuite to throughly test for timeouts. This runs ONLY against particular versions of OpenPegasus because it required adding a new method to OpenPegasus. However, it established that the timeouts apparently now really do work in both python 2 and python 3 with both http and https. (see issue #363)
Clean Code¶
- Removed dangerous default parameter {} from CIMProperty and CIMInstanceName, and replaced it with None. To support that, added support for initializing an empty NocaseDict object from None. (Andreas Maier)
- In cim_obj, changed the use of the deprecated backticks to using %r in the format string (which produces the same result). (Andreas Maier)
- In the constructor of CIMInstanceName, added assertions to some paths that cannot possibly be taken based on the fact that the keybindings attribute is always a NocaseDict. They should be removed at some point. (Andreas Maier)
- Addressed PyLint issues: (Andreas Maier, Karl Schopmeyer)
- Consolidated imports at the top of the module (after module docstring), consistent with the PEP-8 recommendation.
- Ensured order of imports: standard, non-standard, pywbem, local (on a subset of modules only).
- Replaced wildcard imports with specific imports, as much as possible.
- Removed unused imports.
- Addressed PyLint issues that are related to whitespace, continuation indentation, and line length.
- Replaced all real tab characters with spaces.
- Many more PyLint issues
Packaging / Build¶
- Fixed grammatical funkiness in the license text. No change to actual license - still LGPLv2. (Tim Potter)
- Added LICENSE.txt file to release. (Tim Potter)
- Added LICENSE.txt, NEWS, README and INSTALL files to distribution archive. (Andreas Maier)
- Fixed inconsistencies in license text in file headers to consistently say LGPL 2.1 or higher (The LICENSE.txt file has always been LGPL 2.1). (Andreas Maier)
- Removed confusing section about build from INSTALL file, to scope it just to the topic of installation. (Andreas Maier)
- Restructured pywbem/trunk subtree to move pywbem package files into a pywbem subdirectory. (Andreas Maier)
- Added a makefile (invoke ‘make help’ for valid targets). (Andreas Maier)
- Added support for checking the Python source code using PyLint. (Andreas Maier)
- Added support for generating HTML documentation using epydoc, and included the documentation into the distribution archive. The syntax used in Python docstrings is reStructuredText markdown. (Andreas Maier)
- Added support for installing OS-level prerequisites via the new setup.py script commands ‘install_os’ and ‘develop_os’. (Andreas Maier)
- Added support for installing Python-level prerequisites when installing in development mode using the setup.py script command ‘develop’. (Andreas Maier)
pywbem v0.7.0¶
Released: 2008-12-12
Bug Fixes¶
- Fixed enumInstances and references in cim_provider to do a deep copy of the model before filtering instances so provider writers are less surprised. (Bart Whiteley)
- Added CIMDateTime.__cmp__() so that CIMDateTime instances can be compared. (Bart Whiteley)
- Fixed data types of method return values for python providers. (Bart Whiteley)
- Fixed REF array out parameters in tupleparse.py. (Bart Whiteley)
- Fixed Array parameters with no elements. (Bart Whiteley)
- Fixed precision for real32 and real64 types. (Bart Whiteley)
- Fixed Array properties where is_array isn’t set in __init__. (Bart Whiteley)
- Added NocaseDict.__cmp__(self, other). (Bart Whiteley)
- Fixed WBEMConnection.__repr__ for anonymous connections. (Tim Potter)
- Fixed XML encoding of CIMQualifierDeclarations. (Bart Whiteley)
- Fixed EnumerateQualifiers if there are no qualifiers. (Bart Whiteley)
- Fixed InvokeMethod to only send a LOCALCLASSPATH or LOCALINSTANCEPATH, not a CLASSPATH or INSTANCEPATH. (Bart Whiteley)
- Fix unexpected line break in basic auth header for long credentials. (Daniel Hiltgen)
- Fix Host: HTTP header when connecting to a unix domain socket. (Bart Whiteley)
- Fix deprecation warnings with Python 2.6. (Bart Whiteley)
Enhancements¶
- Added support for generating Pegasus provider registration MOF in cim_provider.codegen(). (Bart Whiteley)
- Implemented methods to parse indication export requests. (Bart Whiteley)
- Python provider code generation enhancements. (Bart Whiteley)
- Support for Pegasus Local authentication. (Bart Whiteley)
- Support for Pegasus and OpenWBEM Unix Domain Socket. (Tim and Bart)
- Added support for Pegasus non-compliant EMBEDDEDOBJECT XML attribute. (Bart Whiteley)
- Added CIMQualifierDeclaration.tomof(). (Bart Whiteley)
- Added a powerful MOF compiler. (Bart Whiteley)
- Added property filtering to CIMInstance. (Bart Whiteley)
- Added value attribute to CIMParameter. (Bart Whiteley)
- Rigged CIMInstance to automagically update CIMInstance.path.keybindings as key properties are set. (Bart Whiteley)
- Added cim_provider2.py: A new provider interface. Python providers using this interface can use the cmpi-bindings project within OMC (http://omc-project.org/) to run under any CIMOM supporting the CMPI interface. This is prefered to the old cim_provider.py interface that was used with the Python Provider Managers for OpenWBEM and Pegasus.
- Changed __init__.py to not import anything from cim_provider.py (or cim_provider2.py) into the pywbem namespace. Existing providers based on cim_provider.py can still work with a minor adjustment involving importing CIMProvider from pywbem.cim_provider. The codegen funtion can now be obtained with from pywbem.cim_provider import codegen, or from pywbem.cim_provider2 import codegen or similar.
- Added wbemcli.py command line utility. (Tim Potter)
- Pass keyword args in unix domain socket connection functions down to WBEMConnection(). (Tim Potter)
pywbem v0.6¶
Released: 2007-10-26
Licensing¶
- Relicensed from the GNU GPLv2 to the GNU LGPLv2.
API Changes¶
- Add a type keyword arg and attribute to CIMQualifier, similar to the CIMProperty object, to allow the creation of null qualifiers. (Tim Potter)
- Remove the toxml() method from CIM object classes. Use tocimxml().toxml() instead which specifies the CIM-XML representation of the object. (Tim Potter)
- CIMDateTime class should now be used instead of datetime.datetime and datetime.timedelta.
- Added a new method, CIMInstance.update_existing(). This behaves like update() on a dict, but only assigns new values to existing properties. It skips values for properties not already present in the instance. This is useful for honoring PropertyList within python providers.
Bug Fixes¶
- Explicitly specify charset=”utf-8” in HTTP Content-type header as this is required now by the Pegasus cimserver. (Tim Potter)
- Parse VALUETYPE elements that contain a TYPE attribute. This feature was introduced in version 2.2 of the CIM-XML DTD and produced by some CIMOMs such as the Java WBEM Server. (Tim Potter)
- Don’t require CreateInstance to have the path attribute set but if it is, use the namespace from it. (Tim Potter)
- Allow extrinsic methods to return object references. (Tim Potter)
- Fix CIMInstanceName to support more numeric types of keybindings. (Bart Whiteley)
- Fix datetime values to support utc offset. (Bart Whiteley)
- Fix http client to monitor the connection more closely (RFC 2616 section 8.2.2). Previously, a large request could cause a socket exception with no ability to read the response and respond to an authentication challenge.
- Fix NULL qualifiers to have a (required) type. (Martin Mrazik)
- Fix initialising CIMInstanceName keys from a NocaseDict. (Bart Whiteley)
- Return correct namespace in path for return value from GetInstance. (Tim Potter)
- Numerous bugfixes to Twisted Python client. (Tim Potter)
- Fix for x.509 SSL certificate handling. (Bas ten Berge)
- EnumerateClassNames() now returns an empty list instead of None if there are no classes. (Bart Whiteley)
Enhancements¶
- Support for OpenWBEM password-less local authentication. (Bart Whiteley)
- Support for embedded objects is described in DSP0201-2.2.0 (Bart Whiteley)
- New CIMDateTime class to deal with CIM-isms of datetimes. Most notably, datetime deals with timezone info poorly. (Bart Whiteley)
- Add InvokeMethod() support in Twisted Python client. (Tim Potter)
pywbem v0.5¶
Released: 2006-11-21
API Changes¶
- Many API changes were made to simplify the function and object
interface of PyWBEM. Aspects of just about every CIM operation
call and CIM object have changed. The major changes are:
- The “LocalNamespacePath” keyword argument has been renamed to simply “namespace” for all CIM operations.
- Replaced all object location classes with CIMInstanceName, and all instance classes with CIMInstance. CIMInstanceName now has “host” and “namespace” attributes to fully name a reference to an instance. The CIMInstance class now has a “path” attribute which is of type CIMInstanceName.
- EnumerateInstances() now returns a list of CIMInstance objects (with path attribute set) instead of a list of CIMNamedInstance or tuples of (CIMInstanceName, CIMInstance).
- All representations of properties can now be represented with the CIMProperty class.
- All classes now have a copy() method which return a deep copy of the object. PyWBEM makes extensive use of dictionary objects which are passed by reference in Python. Use the copy() method to create and manipulate objects without modifying them by accident.
Bug Fixes¶
- Fix parse bug when a CIMInstanceName is passed as the localobject parameter to WBEMConnection.InvokeMethod().
- Fix parsing of INSTANCE elements containing PROPERTY.REFERENCE elements bug found by Bart Whiteley. This turns up when processing associations. (Tim Potter)
- Handle extrinsic method calls that don’t return a value or any output parameters. (Tim Potter)
- Fixed parsing of PARAMETER.ARRAY and PARAMETER.REFARRAY to not require optional attrs. (Bart Whiteley)
- Atomic_to_cim_xml string generation for a datetime - was missing a >> ‘.’ in the string. (Norm Paxton)
- InvokeMethod did not provide for None in output parameters. (Norm Paxton)
Enhancements¶
- More parts of the class provider interface have been implemented. (Tim Potter, Bart Whiteley)
- Many case-sensitivity bugs, mostly in __cmp__ methods, were found and fixed. (Tim Potter)
- Implemented a test suite for maintaining backward compatibility and testing new features. (Tim Potter)
- Implemented ExecQuery. (Bart Whiteley)
- Allow a string classname to be passed as the localobject parameter to WBEMConnection.InvokeMethod(). (Tim Potter)
- Add missing qualifiers on array properties. (Bart Whiteley)
- Added code for performing asynchronous WBEM client operations using the Twisted Python framework. (Tim Potter)
- Allow extrinsic method calls that take parameters. (Tim Potter)
- Added cim_http.AuthError exception class. This is raised if the CIMOM returns a 401 (Unauthorized). Now the client can distinguish this condition, and (re)prompt for credentials. (Bart Whiteley)
- Created cim_obj.CIMParameter class. Added return type, class origin, propagated to CIMMethod. CIMParameter object now allows parameter types and qualifiers to be obtained. (Bart Whiteley)
- Implemented case-insensitive keys for property and qualifier dictionaries, as per the CIM specification. (Tim Potter, Bart Whitely)
pywbem v0.4¶
Released: 2005-11-15
Bug Fixes¶
- Correctly calculate value of Content-Length HTTP header to include opening XML stanza. (Szalai Ferenc)
- Fix syntax error when re-raising socket errors. (Pat Knight)
Enhancements¶
- Support for marshaling and unmarshaling CIM dates object into Python datetime objects. (Szalai Ferenc)
- Experimental module for making asynchronous WBEM calls with PyWBEM in Twisted Python. (Tim Potter)
- Add parameter type checking for object location classes. (Tim Potter)
- Allow caller to pass in a dictionary containing the location of the SSL certificate and key files as per the httplib.HTTPSConnection() class constructor. (Pat Knight)
API Changes¶
- Change association provider API functions to take a fixed parameter for the named object instead of a keyword argument. This breaks backward compatibility. (Tim Potter)
- Remove the CIMLocalNamespacePath class and replaced by a Python string. (Tim Potter)
Portability¶
- Don’t use UserDict.DictMixin base class as it only exists in Python 2.3 and higher. (Tim Potter)
Tests¶
- Add tests for parameter type checking for object location classes. (Tim Potter)
- Add tests for string representation of object location classes. (Tim Potter)