Docs: Improved mock support chapter

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

docs/changes.rst

@@ -404,6 +404,8 @@ Enhancements
   consistency with ignoring the path on
   `CIMInstance.tocimxml()/tocimxmlstr()` (as part of fixing issue #1136).
 
+* Improved the complete pywbem documentation (Issue #1115).
+
 Bug fixes
 ^^^^^^^^^
 

docs/mocksupport.rst

@@ -10,8 +10,8 @@ Mock support
 Overview
 --------
 
-The ``pywbem_mock`` module provides mock support that enables usage of the
-pywbem library without a WBEM server.
+The pywbem package contains the ``pywbem_mock`` module which provides mock
+support that enables usage of the pywbem library without a WBEM server.
 
 This is used for testing the pywbem library itself and can also be used for
 the development and testing of Python programs using the pywbem library.
@@ -43,7 +43,7 @@ has a default CIM namespace that can be set upon object creation.
 
 :class:`~pywbem_mock.FakedWBEMConnection` has some additional methods that
 provide for adding CIM classes, instances and qualifier types to its mock
-repository:
+repository, in order to set it up:
 
 * :meth:`~pywbem_mock.FakedWBEMConnection.add_cimobjects` adds
   the specified :ref:`CIM objects`.
@@ -54,24 +54,38 @@ repository:
 * :meth:`~pywbem_mock.FakedWBEMConnection.compile_mof_file` compiles a MOF
   file and adds the resulting CIM objects.
 
-In all cases, certain prerequisite CIM objects must already exist in the target
-namespace of the mock repository for a new CIM object to be successfully added:
-For a CIM class to be added, the superclass of that class as well as CIM
-qualifier types for the qualifiers used by that class must exist.
-For a CIM instance to be added, its CIM creation class must exist.
+In all these ways of adding CIM objects to the mock repository, certain
+prerequisite CIM objects must already exist in the targeted namespace of the
+mock repository for a new CIM object to be successfully added:
 
-Some CIM objects that are used by a CIM object to be added, do not need to
-exist and in fact allow forward references:
-CIM classes specified in reference properties or in reference parameters of
-methods of a class to be added do not need to exist.
-CIM classes specified in qualifiers (for example, in the EmbeddedInstance
-qualifier) of a class to be added do not need to exist.
+* For a CIM class to be added, the superclass of that class as well as CIM
+  qualifier types for the qualifiers used by that class must exist.
+* For a CIM instance to be added, its CIM creation class must exist.
+
+Some CIM objects that are used by a CIM object to be added do not need to
+exist in the mock repository, which in fact allows forward references:
+
+* CIM classes specified in reference properties or in reference parameters of
+  methods of a class to be added do not need to exist.
+* CIM classes specified in qualifiers (for example, in the `EmbeddedInstance`
+  qualifier) of a class to be added do not need to exist.
 
 There are no setup methods to remove or modify CIM objects in the mock
 repository. However, if needed, that can be done by using operation methods
 such as :meth:`~pywbem.WBEMConnection.DeleteClass` or
 :meth:`~pywbem.WBEMConnection.ModifyInstance`.
 
+The mock repository supports two validity checking modes that affect the
+behavior of the faked WBEM operations:
+
+* lite validity checking: Some validity checks are relaxed, allowing instance
+  operations to be performed without requiring that the corresponding classes
+  exist in the mock repository, and class operations without the corresponding
+  qualifier types.
+
+* strict validity checking: The validity checks mentioned above are not
+  relaxed.
+
 The following example demonstrates setting up a faked connection, adding some
 CIM objects defined in a MOF string to its mock repository, and performing a
 few operations:
@@ -169,97 +183,98 @@ Pywbem mock does NOT support:
    HTTP requests or responses.
 7. Generating CIM indications.
 8. Some of the functionality that may be implemented in real WBEM servers such
-   as the ``__Namespace__`` class/provider or the ``CIM_Namespace``
+   as the `__Namespace__` class/provider or the `CIM_Namespace`
    class/provider, because these are WBEM server-specific implementations and
    not WBEM request level capabilities.  Note that such capabilities can be at
    least partly built on top of the existing capabilities by inserting
    corresponding CIM instances into the mock repository.
 
 
-.. _`FakedWBEMConnection methods`:
+.. _`Faked WBEM operations`:
 
-FakedWBEMConnection methods
----------------------------
+Faked WBEM operations
+---------------------
 
-:class:`pywbem_mock.FakedWBEMConnection` defines a set of WBEM Server methods
-corresponding to the WBEMConnection client methods and mocks the communication with
-the WBEMServer) and returns syntatically the same forms of data and
-exceptions as the :class:`pywbem.WBEMConnection` methods.  These methods adher to the
-behavior requirements defined in the DMTF specification :term:`DSP0200` for
-handling requests from the client and returning responses.
+The :class:`pywbem_mock.FakedWBEMConnection` class supports the same WBEM
+operations that are supported by the :class:`pywbem.WBEMConnection` class.
 
-Generally it attempts to get data required by the operation from the fake
-repository created by the user or to put the data from operations that modify
-the server objects (create, modify, and delete operations) into the fake
-repository.  However because this is a simulation of a WBEM server and
-intended to be used primarily for testing there are a number of limitations
-and differences between what these methods do and what a real server would do.
+These faked operations generally adhere to the behavior requirements defined in
+:term:`DSP0200` for handling input parameters and returning a result.
 
-The descriptions below describes differences between the mocker and access to
-a real WBEM server.
+The faked operations get the data to be returned from the mock repository of
+the faked connection, and put the data provided in operation parameters that
+modify objects (create, modify, and delete operations) into that mock
+repository.
 
-Generally these methods provide the same behavior as the corresponding
-methods in a real WBEM Server and the behavior definitions in
-:term:`DSP0200` except for specific limitations and variations.
+However, because the pywbem mock support is only a simulation of a WBEM server
+and intended to be used primarily for testing, there are a number of
+limitations and differences between the faked operations and what a real WBEM
+server would do.
 
+The descriptions below describe differences between the faked operations of
+the pywbem mock support and the operations of a real WBEM server.
 
-.. _`Server class operation methods`:
 
-Server class operation methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _`Faked class operations`:
 
-The methods that get data require the target classes to be in the repository
-before the mock call.  The methods including limitations are:
+Faked class operations
+^^^^^^^^^^^^^^^^^^^^^^
 
-- **GetClass:** Behaves like :meth:`~pywbem.WBEMConnection.GetClass`.
+- **GetClass:** Behaves like :meth:`~pywbem.WBEMConnection.GetClass`. Requires
+  that the class to be returned is in the mock repository.
 
 - **EnumerateClasses:** Behaves like
-  :meth:`~pywbem.WBEMConnection.EnumerateClasses`. Requires that there
-  be one or more top level classes (i.e. no superclass) in the repository
-  if the request does not include the classname parameter.
+  :meth:`~pywbem.WBEMConnection.EnumerateClasses`. Requires that the
+  class specified in the `ClassName` parameter as well as the classes to be
+  returned are in the mock repository.
 
 - **EnumerateClassNames:** Behaves like
-  :meth:`~pywbem.WBEMConnection.EnumerateClassNames`. Requires that there
-  be one or more top level classes (i.e. no subclass) in the mock repository
-  if the request does not include the classname parameter.
+  :meth:`~pywbem.WBEMConnection.EnumerateClassNames`. Requires that the
+  class specified in the `ClassName` parameter as well as the classes to be
+  returned are in the mock repository.
 
 - **CreateClass:** Behaves like
-  :meth:`~pywbem.WBEMConnection.CreateClass`. It requires that any superclass
-  defined in the new class be in the mock repository.
+  :meth:`~pywbem.WBEMConnection.CreateClass`. Requires that the
+  superclass of the new class (if any) is in the mock repository.
 
 - **DeleteClass:** Behaves like
-  :meth:`~pywbem.WBEMConnection.DeleteClass`. This includes deleting all
-  subclasses and instances.
+  :meth:`~pywbem.WBEMConnection.DeleteClass`, with the following difference:
+  This operation additionally deletes all direct and indirect subclasses of the
+  class to be deleted, and all instances of the classes that are being deleted.
+  Requires that the class to be deleted is in the mock repository.
 
-- **ModifyClass:** Currently not implemented. Returns CIMError, not supported
+- **ModifyClass:** Currently not implemented.
 
 
-.. _`Server CIMQualifierDeclaration operation methods`:
+.. _`Faked qualifier operations`:
 
-Server CIMQualifierDeclaration operation methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Faked qualifier operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **SetQualifier:** Behaves like :meth:`~pywbem.WBEMConnection.SetQualifier`.
-
+  Requires that the specified qualifier type is in the mock repository.
+  
 - **GetQualifier:** Behaves like :meth:`~pywbem.WBEMConnection.GetQualifier`.
+  Requires that the specified qualifier type is in the mock repository.
 
 - **EnumerateQualifiers:** Behaves like
   :meth:`~pywbem.WBEMConnection.EnumerateQualifiers`.
+  Requires that the qualifier types to be returned are in the mock repository.
 
 
-.. _`Server CIMInstance operation methods`:
+.. _`Faked instance operations`:
 
-Server CIMInstance operation methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Faked instance operations
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The methods that get data require instances in the
 repository for the instances to be recovered.  We allow some of these methods to
 try to return data if the class repository is empty but they may react differently
 if there are classes in the repository.
 
-- **GetInstance:** Behaves like :meth:`~pywbem.WBEMConnection.GetInstance` except
-  that the LocalOnly option depends only on instance class_origin attribute
-  of each property if repo_lite is True
+- **GetInstance:** Behaves like :meth:`~pywbem.WBEMConnection.GetInstance`,
+  except for these differences: The `LocalOnly` parameter depends only on
+  instance. The class_origin attribute of each property if repo_lite is `True`.
 
 - **EnumerateInstances:** Behaves like
   :meth:`~pywbem.WBEMConnection.EnumerateInstances` except that what it
@@ -303,10 +318,10 @@ if there are classes in the repository.
   TODO: Not done. Clarify when we finish code.
 
 
-.. _`Server WBEM associators and reference operation methods`:
+.. _`Faked association operations`:
 
-Server associators and reference operation methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Faked association operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The fake versions of the esponders for these methods allow both class and
 instance requests.  At the same time, they allow mock repositories that
@@ -334,10 +349,10 @@ corresponding classes. They include the following methods:
   limitations.
 
 
-.. _`Server InvokeMethod  operation methods`:
+.. _`Faked method invocation operation`:
 
-Server InvokeMethod operation method
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Faked method invocation operation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The fake InvokeMethod behaves like :meth:`~pywbem.WBEMConnection.InvokeMethod`.
 
@@ -425,10 +440,11 @@ of the definition and execution of InvokeMethod.
     print('return value %s' result[0])
     print('Return parameters %s' % (result[1],))
 
-.. _`Server pull operations methods`:
 
-Server pull operations methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _`Faked pull operations`:
+
+Faked pull operations
+^^^^^^^^^^^^^^^^^^^^^
 
 The fake pull operations implement all of the Open and Pull WBEM server
 methods with the same behavior as the real operations except as follows.
@@ -449,12 +465,12 @@ methods with the same behavior as the real operations except as follows.
 - TODO Should we name the pull operations to be complete
 
 
-.. _`Pywbem ClientIter... Operations`:
+.. _`Faked iteration operations`:
 
-Pywbem ClientIter... Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Faked iteration operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Because these opertions do not directly call the server but are simply a
+Because these operations do not directly call the server but are simply a
 layer on top of the basic server communication methods like
 EnumerateInstances, OpenEnumerateInstances, etc. hese operations all execute
 with the same behavior as the real operations including use of the

pywbem_mock/_wbemconnection_mock.py

@@ -19,13 +19,10 @@
 #
 
 """
-Mock WBEMConnection to allow pywbem users to test the pywbem client without
-requiring a running WBEM server. This package mocks the WBEMConnection
-methods that communicate with WBEMServers and mantain a fake server
-repository that is the source and destination for information to
-be used by the methods mocked.
+Mock support for the WBEMConnection class to allow pywbem users to test the
+pywbem client without requiring a running WBEM server.
 
-For the module-level documentation, see mocksupport.rst.
+For documentation, see mocksupport.rst.
 """
 
 from __future__ import absolute_import, print_function