From 955cad83858b41b158f94448f838ab6dcc1da5b5 Mon Sep 17 00:00:00 2001 From: Chris Lenk Date: Tue, 13 Mar 2018 16:01:42 -0400 Subject: [PATCH] Clarify serialization in documentation --- docs/guide/serializing.ipynb | 151 ++++++++++++++++++++++++++++++----- stix2/base.py | 2 +- 2 files changed, 134 insertions(+), 19 deletions(-) diff --git a/docs/guide/serializing.ipynb b/docs/guide/serializing.ipynb index 4499677..1046d9f 100644 --- a/docs/guide/serializing.ipynb +++ b/docs/guide/serializing.ipynb @@ -4,7 +4,6 @@ "cell_type": "code", "execution_count": 1, "metadata": { - "collapsed": true, "nbsphinx": "hidden" }, "outputs": [], @@ -23,9 +22,8 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 2, "metadata": { - "collapsed": true, "nbsphinx": "hidden" }, "outputs": [], @@ -68,7 +66,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 3, "metadata": {}, "outputs": [ { @@ -144,12 +142,12 @@ ".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n", ".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
{\n",
        "    "type": "indicator",\n",
-       "    "id": "indicator--5eac4517-6539-4e48-ab51-7d499f599674",\n",
-       "    "created": "2017-11-09T19:21:06.285Z",\n",
-       "    "modified": "2017-11-09T19:21:06.285Z",\n",
+       "    "id": "indicator--85773ceb-c768-45f6-bb04-b4d813809e48",\n",
+       "    "created": "2018-03-13T19:49:53.392Z",\n",
+       "    "modified": "2018-03-13T19:49:53.392Z",\n",
        "    "name": "File hash for malware variant",\n",
        "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
-       "    "valid_from": "2017-11-09T19:21:06.285451Z",\n",
+       "    "valid_from": "2018-03-13T19:49:53.392627Z",\n",
        "    "labels": [\n",
        "        "malicious-activity"\n",
        "    ]\n",
@@ -160,7 +158,7 @@
        ""
       ]
      },
-     "execution_count": 2,
+     "execution_count": 3,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -179,12 +177,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "However, the string representation can be slow, as it sorts properties to be in a more readable order. If you need performance and don't care about the human-readability of the output, use the object's serialize() function:"
+    "However, the string representation can be slow, as it sorts properties to be in a more readable order. If you need performance and don't care about the human-readability of the output, use the object's `serialize()` function:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -258,14 +256,14 @@
        ".highlight .vg { color: #19177C } /* Name.Variable.Global */\n",
        ".highlight .vi { color: #19177C } /* Name.Variable.Instance */\n",
        ".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n",
-       ".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
{"valid_from": "2017-11-09T19:21:06.285451Z", "name": "File hash for malware variant", "created": "2017-11-09T19:21:06.285Z", "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']", "labels": ["malicious-activity"], "modified": "2017-11-09T19:21:06.285Z", "type": "indicator", "id": "indicator--5eac4517-6539-4e48-ab51-7d499f599674"}\n",
+       ".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
{"name": "File hash for malware variant", "labels": ["malicious-activity"], "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']", "type": "indicator", "id": "indicator--85773ceb-c768-45f6-bb04-b4d813809e48", "created": "2018-03-13T19:49:53.392Z", "modified": "2018-03-13T19:49:53.392Z", "valid_from": "2018-03-13T19:49:53.392627Z"}\n",
        "
\n"
       ],
       "text/plain": [
        ""
       ]
      },
-     "execution_count": 6,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -273,25 +271,142 @@
    "source": [
     "print(indicator.serialize())"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you need performance but also need human-readable output, you can pass the `indent` keyword argument to `serialize()`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "
{\n",
+       "    "name": "File hash for malware variant",\n",
+       "    "labels": [\n",
+       "        "malicious-activity"\n",
+       "    ],\n",
+       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
+       "    "type": "indicator",\n",
+       "    "id": "indicator--85773ceb-c768-45f6-bb04-b4d813809e48",\n",
+       "    "created": "2018-03-13T19:49:53.392Z",\n",
+       "    "modified": "2018-03-13T19:49:53.392Z",\n",
+       "    "valid_from": "2018-03-13T19:49:53.392627Z"\n",
+       "}\n",
+       "
\n"
+      ],
+      "text/plain": [
+       ""
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "print(indicator.serialize(indent=4))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The only difference between this and the string representation from using `str()` is that this will not sort the keys. This works because the keyword arguments are passed to `json.dumps()` internally."
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 2",
+   "display_name": "Python 3",
    "language": "python",
-   "name": "python2"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
-    "version": 2
+    "version": 3
    },
    "file_extension": ".py",
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython2",
-   "version": "2.7.12"
+   "pygments_lexer": "ipython3",
+   "version": "3.6.3"
   }
  },
  "nbformat": 4,
diff --git a/stix2/base.py b/stix2/base.py
index fc13094..6bc3dd4 100644
--- a/stix2/base.py
+++ b/stix2/base.py
@@ -187,7 +187,7 @@ class _STIXBase(collections.Mapping):
         Args:
             pretty (bool): If True, output properties following the STIX specs
                 formatting. This includes indentation. Refer to notes for more
-                details.
+                details. (Default: ``False``)
             **kwargs: The arguments for a json.dumps() call.
 
         Returns: