Clarified and improved copy() methods of NocaseDict and CIM objects

Details:

1. The copy() methods of `NocaseDict`and of the CIM object classes were
   not quite specific as to whether they produce deep or shallow copies.

   This change clarifies that they produce middle-deep copies, where
   some mutable leaf attributes are not copied and thus are shared between
   original and copy.

2. Added a note that copy.copy() and copy.deepcopy() can be used to
   create completely shallow or completely deep copies, which was the reason
   to leave the middle-deep implementation as it was and just documented
   it properly.

3. Removed one level of superflous copies of dictionaries
   in the copy() methods of the CIM object classes. These dictionaries
   are already copied in the setter merthods for the respective attribute.

4. Changed the path argument of CIMInstance to be deep copied, because it
   may be modified by setting properties.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

docs/changes.rst

@@ -22,6 +22,12 @@ Released: not yet
 
 **Incompatible changes:**
 
+* Changed the `path` argument of `CIMInstance` to be deep copied, because it 
+  may be modified by setting properties. This is only incompatible if your
+  code relies on the init method modifying its `path` input argument. If your
+  code relies on that, it is highly recommended that you decouple such
+  dependencies (Issue #1251).
+
 **Deprecations:**
 
 * Deprecated the `tocimobj()` function because it has some inconsistencies,
@@ -83,6 +89,14 @@ Released: not yet
   through the items of the value mapping, returning tuples of the binary value
   (or a range thereof), and the `Values` string. (Issue #1153)
 
+* Docs: Clarified that the `copy()` methods of `NocaseDict` and of the CIM object
+  classes produce middle-deep copies, whereby mutable leaf attributes are not
+  copied and thus are shared between original and copy (Issue #1251).
+
+* Docs: Added a note to the description of the `copy()` methods of the CIM
+  objects that states that `copy.copy()` and `copy.deepcopy()` can be used
+  to create completely shallow or completely deep copies (Issue #1251).
+
 **Cleanup**
 
 * Moved class `NocaseDict` into its own module (Issue #848).
@@ -91,6 +105,10 @@ Released: not yet
 
 * Cleanup mof_compiler use of args[0] and args[1] with CIMError. (Issue #1221)
 
+* Removed one level of superflous copies of dictionaries in the `copy()`
+  methods of the CIM object classes. These dictionaries are already copied
+  in the setter methods for the respective attributes (Issue #1251).
+
 **Known issues:**
 
 * See `list of open issues`_.

pywbem/_nocasedict.py

@@ -408,8 +408,16 @@ def clear(self):
 
     def copy(self):
         """
-        Return a shallow copy of the dictionary (i.e. the keys and values are
-        not copied).
+        Return a copy of the dictionary.
+
+        This is a middle-deep copy; the copy is independent of the original in
+        all attributes that have mutable types except for:
+
+        * The values in the dictionary
+
+        Note that the Python functions :func:`py:copy.copy` and
+        :func:`py:copy.deepcopy` can be used to create completely shallow or
+        completely deep copies of objects of this class.
         """
         result = NocaseDict()
         result._data = self._data.copy()  # pylint: disable=protected-access