Merge pull request #580 from robthew/immutability-issue

Added documentation about immutability issues

Author: rpiazza

docs/guide/creating.ipynb

@@ -1113,6 +1113,42 @@
     "\n",
     "print(ip4_valid_refs.serialize(pretty=True))"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Immutability Issues\n",
+    "\n",
+    "It's been shown above that changing an object's properties will trigger an ImmutableError, but because List and Dictionary properties retain their built-in content-modification functions, it is possible to modify some of an object's data. ImmutableError's are triggered when the object ID of a field is changed. Strings are inherently immutable, so any attempt to modify their content results in a new object being created - with a new ID - triggering the ImmutableError. But using the content-modification functions of Lists and Dictionaries does not change the underlying object ID, and therefore, doesn't trigger the error.\n",
+    "\n",
+    "This does violate the design principle of STIX 2 being immutable by default, but it is something to be aware off, if only to avoid doing it by mistake. It also allows the possibility of complex objects being built up by appending to fields, rather than creating objects all in one action.\n",
+    "\n",
+    "Here an Identity object is created. Fields like 'name' and 'identity_class' are immutable, but the 'roles' data can be modified using the List operations 'clear' and 'append'."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stix2 import Identity\n",
+    "\n",
+    "identity1 = Identity(\n",
+    "    x_custom=\"IRF system\",\n",
+    "    name=\"IRF\",\n",
+    "    description=\"Incident Reporting Form (IRF) system\",\n",
+    "    identity_class=\"system\",\n",
+    "    roles=[\"director\"],\n",
+    "    sectors=[\"commercial\", \"defense\"],\n",
+    ")\n",
+    "\n",
+    "identity1.roles.clear()\n",
+    "identity1.roles.append(\"cleared-dod-contractor\")\n",
+    "\n",
+    "print(identity1.serialize(pretty=True))"
+   ]
   }
  ],
  "metadata": {

docs/overview.rst

@@ -20,9 +20,13 @@ To accomplish these goals, and to incorporate lessons learned while developing
 ``python-stix`` (for STIX 1.x), several decisions influenced the design of the
 ``stix2`` library:
 
-1. All data structures are immutable by default. In contrast to python-stix,
+1. All data structures are meant to be immutable by default. In contrast to python-stix,
    where users would create an object and then assign attributes to it, in
-   ``stix2`` all properties must be provided when creating the object.
+   ``stix2`` all properties should be provided when creating the object. Changing a property 
+   after creation will trigger an Immutability error, but some data structures like 
+   Lists and Dictionaries retain functions that allow for content modification without 
+   triggering an Immutability error. Data can be added to or removed from these structures 
+   after creation, which does allow for some flexibility in building an object.
 2. Where necessary, library objects should act like ``dict``'s. When treated as
    a ``str``, the JSON representation of the object should be used.
 3. Core Python data types (including numeric types, ``datetime``) should be used