--------------
Released: 2020-06-24
This is a beta version of the upcoming version 1.0.0. Pip will only install
this version if explicitly requested, e.g. using any of these commands::
$ pip install pywbem==1.0.0b1
$ pip install --pre pywbem
**Incompatible changes:**
Because pywbem 1.0.0 is a major change, a number of significant incompatibilites
have been incorporated. The following subsections summarize these changes and provide
details of the changes themselves and the reasons for the changes.
*Summary of incompatible changes:*
The details, alternatives, and reasons for these incompatible changes is shown
below this list.
* Removed Python 2.6 support.
* Migrated pywbem to use the 'requests' Python package for HTTP/HTTPS pywbem
client to WBEM server communication. This caused some restrictions, see
the detailed decription of incompatible changes, below.
* Removed the following deprecated functionality:
- `WBEMConnection` `verify_callback` init parameter.
- `WBEMConnection` `**extra` keyword arguments from operation methods.
- Ordering for `NocaseDict`, `CIMInstanceName`, `CIMInstance` and `CIMClass`
objects.
- `WBEMConnection` properties: `url`, `creds`, `x509`, `ca-certs`,
`no_verification`, and `timeout` setter methods. They are now read-only
- `WBEMConnection` `method_call()` and imethod_call()` methods.
- `WBEMConnection` `operation_recorder` property.
- `CIMInstance` property `property_list` and the same-named init parameter.
- `pywbem.tocimxml()` support for value of `None`.
- `CIMInstance.tomof()` `indent` parameter.
- `pywbem.byname()` internal function.
- `pywbem.tocimobj()` function.
- `wbemcli` command.
* Made the `MOFWBEMConnection` class (support for the MOF compiler) internal.
* Changed exceptions behavior:
- MOF compilation methods of `MOFCompiler` and `FakedWBEMConnection` raises
exceptions based on class `pywbem.MOFCompileError`.
- Some methods of `ValueMapping` to use `pywbem.ModelError`.
- Some methods of `WBEMServer` to raise the new exception `pywbem.ModelError`.
- `WBEMConnection` request method responses added a new exception
`pywbem.HeaderParseError` derived from `pywbem.ParseError`.
* Made all sub-namespaces within the pywbem namespace private, except for
'pywbem.config'.
* Mock WBEM Server (experimental):
- Replaced the `add_method_callback()` method in
`FakedWBEMConnection` with user-defined providers.
- Removed the `conn_lite` init parameter and mode of `FakedWBEMConnection`.
- Changed the logging behavior of the MOF compilation methods of
`FakedWBEMConnection` so that the default is for the caller to display
exceptions rather than the MOF compiler logger.
- Changed the default behavior to ignore `IncludeQualifiers` and
`IncludeClassOrigin` parameters for GetInstance and EnumerateInstances
operations of the mock WBEM server.
*Incompatible change details:*
* Removed Python 2.6 support. The Python Software Foundation stopped supporting
Python 2.6 in October 2013. Since then, many Python packages have continued
releasing versions for Python 2.6, including pywbem. In 2017 and
2018, a number of Python packages have removed support for Python 2.6 and it
has become an increasingly difficult task for pywbem to keep supporting
Python 2.6. For this reason, Python 2.6 support has been removed from pywbem
in its 1.0.0 version.
This allowed eliminating a lot of Python version dependent code,
eliminating the dependency on the unittest2 package, and lifting a number
of restrictions in test code.
* Migrated pywbem to use the 'requests' Python package for all HTTP/HTTPS
communication between the pywbem client and the WBEM server replacing httplib
and different ssl implementations for python 2 and 3. This eliminates
several python 2/3 pywbem differences and simplifies the installation and setup
of pywbem.
This results in the following changes:
- Changed the behavior of the default value `None` for the `ca_certs`
parameter of `WBEMConnection`: Previously, it caused the first existing
directory from a predefined set of directories to be used as the
certificate directory. Now, it causes the certificates provided by the
'certifi' Python package to be used. That package provides the Mozilla
Included CA Certificate List.
- Removed support for specifying multiple directory paths or file paths
from the `ca_certs` parameter of `WBEMConnection`. Now, only a single
directory path or file path can be specified, or `None` (see previous item).
- A non-existing path specified for the `ca_certs` parameter of
`WBEMConnection` now raises `IOError`. Previously, the directory or file
was simply skipped (and subsequently, verification failed).
- Removed support for the 'OWLocal' authentication scheme that was supported
for the OpenWBEM server, and the 'Local' authentication scheme that was
supported for the OpenPegasus server. Pywbem now supports only the 'Basic'
authentication scheme.
- Removed support for communicating with WBEM servers using UNIX domain
sockets by specifying a file-based URL. Use the standard http and https
protocols instead.
- The installation of pywbem no longer uses the `pywbem_os_setup.sh/.bat`
scripts because there are no more prerequisite OS-level packages needed
for installing pywbem. If you have automated the pywbem installation,
this step should be removed from your automation.
- Removal of the `WBEMConnection` `verify_callback` method.
* Removed the `verify_callback` parameter of `WBEMConnection`. It was
deprecated in pywbem 0.9.0, and was not supported in Python 3. The 'requests'
package provides the commonly accepted certificate verification within the
package itself. (See issue 1928)
* Removed the `**extra` keyword arguments from `WBEMConnection` operation methods.
Such arguments were passed on to the WBEM server, but they are not needed
because all parameters defined by the CIM-XML protocol are supported as named
arguments to these methods. This would only be incompatible if a WBEM server
supports non-standard parameters or keyword variables were misnamed which
would have been ignored and not used but now results in exceptions. (See
issue 1415)
* Removed the deprecated support for ordering `NocaseDict`, `CIMInstanceName`,
`CIMInstance` and `CIMClass` objects. The ordering of such dictionaries was
never supported with pywbem on Python 3, and for Python 2 it had been
deprecated since pywbem 0.12.0. The user should do any required
ordering. (See issue 1926).
* Removed the deprecated ability to set the following properties of class
`WBEMConnection`: `url`, `creds`, `x509`, `ca-certs`, `no_verification`,
and `timeout`. These properties should not be set after the connection is
defined as the results on the connection are unpreditable.
* Removed the deprecated methods `method_call()` and imethod_call()` and the
deprecated property `operation_recorder` from class `WBEMConnection`. Users
should always use the request methods (ex. GetInstance).
* Removed the deprecated property `property_list` and the same-named init
parameter from class `CIMInstance`. The behavior of this parameter was
undefined and incomplete.
* Removed the deprecated ability to support a value of `None` for
`pywbem.tocimxml()`.
* Removed the deprecated `indent` parameter of `CIMInstance.tomof()`.
* Removed the deprecated internal function `pywbem.byname()`.
* Removed the deprecated function `pywbem.tocimobj()`. The replacement for this
method is to use the function `cimvalue()`.
* Removed the `wbemcli` command that was deprecated in pywbem 0.15.0. The
recommended replacement is the `pywbemcli` command from the 'pywbemtools'
package on Pypi: https://pypi.org/project/pywbemtools/. Some of the reasons
for the removal are: (See issue 1932)
- Wbemcli did not have a command line mode (i.e. a non-interactive mode), but
pywbemcli does.
- The interactive mode of wbemcli was more of a programming environment than
an interactive CLI, and that makes it harder to use than necessary.
Pywbemcli has an interactive mode that uses the same commands as in the
command line mode. If you need an interactive programming prompt e.g. for
demonstrating the pywbem API, use the interactive mode of the python
command, or Python's IDLE.
- Pywbemcli provides more functionality than wbemcli, e.g. server commands,
persistent connections, class find, instance count, or multiple output
formats.
* Made the `MOFWBEMConnection` class internal and removed it from the pywbem
documentation. It has an inconsistent semantics and should not be used by
users. (See issue 2001).
* Exception changes:
* Changed the type of exceptions that are raised by methods of
`pywbem.ValueMapping` for cases where the value-mapped CIM element has
issues, as follows:
- From `TypeError` to `pywbem.ModelError`, if the value-mapped CIM element
is not integer-typed.
- From `ValueError` to `pywbem.ModelError`, if an item of the `ValueMap`
qualifier is not an integer.
The exceptions occur only with model definitions that are invalid and
do not occur in the CIM Schema published by DMTF.
This change is incompatible only for users that handle these exceptions
specifically in their code. (See issue 1429)
* Changed the exception behavior of the MOF compilation methods of the
`MOFCompiler` and `FakedWBEMConnection` classes to no longer raise
`CIMError`, but to raise the following exceptions derived from a new base
class `MOFCompileError`:
- `MOFParseError` MOF parsing errors. This class already existed and was
already used for this purpose.
- `MOFDependencyError`: New class for MOF dependency errors (e.g. superclass
not found).
- `MOFRepositoryError`: New class for errors returned from the target CIM
repository. The `CIMError` exception raised by the CIM repository is
attached to that exception in its attribute `cim_error`.
If you are using these MOF compilation methods, please change your catch
of exceptions accordingly. (See issue 1235)
* Changed the `CIMError` exceptions that were raised by pywbem code in several
`WBEMServer` methods to now raise `ModelError`, for cases where the model
implemented by the server has issues.
(See issue 1423)
* Added a new exception `pywbem.HeaderParseError` derived from
`pywbem.ParseError` that is used to report HTTP header issues in the CIM-XML
response. Previously, `HTTPError` had been used for that purpose, misusing
its integer-typed `status` attribute for the message string. This is actually
a bug fix, but because it changes the exception type, it is also an
incompatible change for users that handle exceptions specifically.
(See issue 2110)
* Made all sub-namespaces within the pywbem namespace private, except for
pywbem.config. Specifically, renamed the following modules by prepending
an underscore character: cim_constants.py, cim_http.py, cim_obj.py,
cim_operations.py, cim_types.py, cim_xml.py, exceptions.py, mof_compiler.py,
moflextab.py, mofparsetab.py, tupleparse.py, tupletree.py.
Using these sub-namespaces had been deprecated in pywbem 0.8.0.
This change is compatible for users that followed the recommendation
to import only the symbols from the pywbem namespace. Users that imported
symbols from these sub-namespace should now import them from the pywbem
namespace. If you miss a symbol in the pywbem namespace, it was likely a
symbol that is not part of the public pywbem API. (See issue 1925)
* Mock WBEM Server (experimental):
* Removed the `add_method_callback()` method and the `methods` property
from the `FakedWBEMConnection` class. This has been replaced by
the user-defined provider concept where the user defines and registers a
subclass to the class MethodProvider which implements the InvokeMethod
responder in that user-defined provider. The 'mock WBEM server' section
of the documentation and module documentation for the MethodProvider
and InstanceWriteProvider document creation of unser-defined providers
(See issue 2062).
* Removed the `conn_lite` init parameter and mode of operation of
`FakedWBEMConnection`. The lite mode turned out too simplistic for mock
testing and of no real value, while adding complexity. Users must include
classes and qualifier declarations. Most mock environments start with
classes and qualifier declarations in any case and the tools to add them
are simple. (See issue 1959)
* Changed the logging behavior of the MOF compilation methods
`FakedWBEMConnection.compile_mof_string()` and `compile_mof_file()`
(consistent with the new `compile_schema_classes()` method) to be able to
do no logging, by specifying `None` for the `log_func` init parameter of
`MOFCompiler`. This is now the default.
MOF compile errors no are longer printed to stdout by default. To continue
printing the MOF compile errors to stdout, print the exception in your code.
(See issue 1997)
* Changed the behavior for the IncludeQualifiers and IncludeClassOrigin
parameters on the GetInstance and EnumerateInstances operations of the
mock WBEM server.
The default is now to ignore the provided parameters and never include
either attribute in the returned instances whereas, in previous versions the
provided parameters determined whether they were returned. This behavior
may be changed back to how it was in previous versions by modifying config
variables in the new 'pywbem_mock.config' module.
Reason for the change was that the behavior of these parameters was
inconsistent between versions of :term:`DSP0200` and the new behavior
implements the recommended default behavior. (See issue 2065)
**Deprecations:**
* Deprecated Python 2.7 and 3.4 support in pywbem, that are both beyond their
End-Of-Life date.
* Deprecated the `compile_dmtf_schema()` method in `FakedWBEMConnection` in
favor of a new method `compile_schema_classes()` that does not automatically
download the DMTF schema classes as a search path, but leaves the control over
where the search path schema comes from, to the user.
* Deprecated the `schema_mof_file` property in `DMTFCIMSchema` in favor of
a new property `schema_pragma_file` since this is the file that contains all
of the MOF pragmas defining the locations of the class MOF files in a
set of directories.
**Bug fixes:**
* Docs: Fixed issues in Listener and SubscriptionManager examples
(See issue 1768)
* Test: Added testcases to the cim_xml module, and migrated from unittest to
pytest.
* Fixed a standards compliance issue. DSP0201/203 version 2.4 introduced the
requirement to set the TYPE attribute on KEYVALUE elements. In operation
requests sent to the WBEM server, pywbem now sets the TYPE attribute of the
KEYVALUE element for keybinding values that are specified as CIM data types
(e.g. pywbem.Uint8, string, bool). For keybinding values that are specified
as Python int/float types or as None, pywbem continues not to set the TYPE
attribute on KEYVALUE elements. This is sufficient to be fully standards
compliant because it is always possible for a user to cause the TYPE attribute
to be set. In operation responses received from the WBEM server, pywbem
continues to tolerate an absent TYPE attribute, in order to accomodate WBEM
servers that implement DSP0201/203 before version 2.4. (See issue 2052)
* Documented the limitation that the `CORRELATOR` element introduced in
DSP0201/203 version 2.4 is not supported by pywbem. (related to issue 2053)
* Test: Fixed a bug introduced in 0.14.5 where the manualtest scripts failed
with invalid relative import. (see issue 2039)
* Test: Fixed incorrect coverage reported at the end of the pytest run,
by increasing the minimum version of the coverage package to 4.5.2.
(See pywbemtools issue 547)
* Added missing attributes to the test client recorder
(class TestClientRecorder) (see issue 2118).
* Fixed issue where DMTFCIMSchema/build_schema_mof creates the new cim_schema
pragma list in order different than the DMTF defined file. In some rare
cases this could cause an issue because the DMTF carefully ordered the
class pragmas to avoid and issues of dependencies, etc. Note that if only
leaf classes are use there should never be an issue. (See issue 2223)
* Fixed issue in MOF compiler where compile_string() modifies the
default_namespace of the MOF_Compiler handle parameter which is some subclass
of WBEMConnection. This impacts at least the pywbem_mock environment since
compiling MOF into a namespace that is not the connection default_namespace
changes the default_namespace to that defined for the compile_string. This
required extending all subclasses of MOFCompiler.BaseRepository to handle an
optional namespace parameter on CreateClass, ModifyClass, GetClass,
CreateInstance, etc. methods including the implementation in pywbem_mock.
(See issue 2247)
* Removed the incorrect statement about deprecated comparison operators in the
`NocaseDict` class - these operators had already returned errors.
* Accomodated the newly released flake8 version 3.8.1 by removing the
pinning of pyflakes to <2.2.0, and adjusting the source code of pywbem
to get around the new flake8 messages E123, E124, E402.
**Enhancements:**
* For the end2end tests, extended the definitions in
`tests/profiles/profiles.yml` by the ability to specify the profile version.
(See issue 1554)
* Improved test coverage of function tests by verifying the last_request,
last_raw_request, last_reply, and last_raw_reply attributes of a connection.
* Migrated the communication between the pywbem client and WBEM servers to
to use the 'requests' Python package. This greatly cleaned up the code,
made the code common again between Python 2 and Python 3, and removed
any prerequisite OS-level packages, thus simplifying the installation of
pywbem again to what is expected for a pure Python package.
* Added more unit tests for the cim_http.py module and converted it to
pytest. (See issue 1414)
* Added a `request_data` attribute to the `HTTPError` and `CIMError`
exceptions and a `response_data` attribute to the `HTTPError` exception
for storing the CIM-XML request or response, respectively, in order to
provide additional context for the error. The `ParseError` exception and its
subclasses already had `request_data` and `response_data` attributes.
(See issue 1423)
* Added proxy support to the `WBEMConnection` class, by adding a `proxies`
init parameter and attribute, utilizing the proxy support of the requests
package. (see issue 2040)
* Add property to pywbem_mock `FakedWBEMConnection` to allow the user to modify
the mocker behavior to forbid the use of the pull operations.
(See issue 2126)
* Refactor pywbem_mock into more consistent components separating the
mock repository from the component that represents a CIMOM. (see issue 2062)
* Refactor pywbem_mock to separate the CIM repository from the class
`FakedWBEMConnection`. This creates a new file _cimrepository.py that
implements a CIM server repository. (See issue 2062)
* Enhance `FakedWBEMConnection` to allow user-defined providers for specific
WBEM request operations. This allows user-defined providers for selected
instance requests (CreateInstance, ModifyInstance, DeleteInstance) and for
the InvokeMethod. Includes the capability to register these providers with
a method `register_provider` in `FakedWBEMConnection`. This also creates
a CIM_Namespace provider to handle the CIM_Namespace class in the interop
namespace. See issue 2062)
* Changed format 'standard' of `CIMInstanceName.to_wbem_uri()` to sort the
keys in the resulting WBEM URI. (See issue 2264)
* Added a new method `FakedWBEMConnection.compile_schema_classes()` that does
not automatically download the DMTF schema classes as a search path, but
leaves the control over where the search path schema comes from, to the user.
See the Deprecations section.
**Cleanup:**
* Improved performance when setting WBEMConnection.debug by prettifying the
request and reply XML only when actually accessed. (See issue 1572)
* Removed pywbem_mock conn_lite mode. (See issue 1959)
* Fixed an error in the CIM-XML creation where the IMETHODRESPONSE element did
not support output parameters. The IMETHODRESPONSE element is not used in the
pywbem client, though.
* Fixed an error in the CIM-XML creation where the IRETURNVALUE element did not
support multiple return objects. The IRETURNVALUE element is not used in the
pywbem client, though.
* Fixed issue where the MOF compiler was using an instance path defined when
the compiler built the instance as the instance alias instead of the
instance path returned by the CreateInstance method. The issue is that
the instance path defined in the compiler may not be complete and the
only correct instance path is the path returned by the CreateInstance.
Mof compiler alias now build with return from CreateInstance and the creation
of the path has been moved from the compiler instanceDeclaration to the
CreateInstance method defined in the compiler repo. For the tests that
means that the path creation is in MOFWBEMConnection.CreateInstance.
(See issue 1911)
* Test: Converted WBEMListener tests from unittest to pytest. (See issue 2179)