Add notebook docs, fix package distribution

docs/guide/support.ipynb

@@ -0,0 +1,235 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### How imports will work\n",
+    "\n",
+    "Imports can be used in different ways depending on the use case and support levels.\n",
+    "\n",
+    "People who want to (in general) support the latest version of STIX 2.X without making changes, implicitly using the latest version"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import stix2\n",
+    "\n",
+    "stix2.Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "or,"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stix2 import Indicator\n",
+    "\n",
+    "Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "People who want to use an explicit version"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import stix2.v20\n",
+    "\n",
+    "stix2.v20.Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "or,"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stix2.v20 import Indicator\n",
+    "\n",
+    "Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "or even,"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import stix2.v20 as stix2\n",
+    "\n",
+    "stix2.Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The last option makes it easy to update to a new version in one place per file, once you've made the deliberate action to do this.\n",
+    "\n",
+    "People who want to use multiple versions in a single file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import stix2\n",
+    "\n",
+    "stix2.v20.Indicator()\n",
+    "\n",
+    "stix2.v21.Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "or,"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stix2 import v20, v21\n",
+    "\n",
+    "v20.Indicator()\n",
+    "v21.Indicator()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "or (less preferred):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stix2.v20 import Indicator as Indicator_v20\n",
+    "from stix2.v21 import Indicator as Indicator_v21\n",
+    "\n",
+    "Indicator_v20()\n",
+    "Indicator_v21()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### How parsing will work\n",
+    "If the ``version`` positional argument is not provided. The data will be parsed using the latest version of STIX 2.X supported by the `stix2` library.\n",
+    "\n",
+    "You can lock your `parse()` method to a specific STIX version by"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stix2 import parse\n",
+    "\n",
+    "indicator = parse(\"\"\"{\n",
+    "    \"type\": \"indicator\",\n",
+    "    \"id\": \"indicator--dbcbd659-c927-4f9a-994f-0a2632274394\",\n",
+    "    \"created\": \"2017-09-26T23:33:39.829Z\",\n",
+    "    \"modified\": \"2017-09-26T23:33:39.829Z\",\n",
+    "    \"labels\": [\n",
+    "        \"malicious-activity\"\n",
+    "    ],\n",
+    "    \"name\": \"File hash for malware variant\",\n",
+    "    \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n",
+    "    \"valid_from\": \"2017-09-26T23:33:39.829952Z\"\n",
+    "}\"\"\", version=\"2.0\")\n",
+    "print(indicator)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Keep in mind that if a 2.1 or higher object is parsed, the operation will fail."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### How will custom work\n",
+    "\n",
+    "CustomObjects, CustomObservable, CustomMarking and CustomExtensions must be registered explicitly by STIX version. This is a design decision since properties or requirements may change as the STIX Technical Specification advances.\n",
+    "\n",
+    "You can perform this by,"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import stix2\n",
+    "\n",
+    "# Make my custom observable available in STIX 2.0\n",
+    "@stix2.v20.observables.CustomObservable('x-new-object-type',\n",
+    "                                    ((\"prop\", stix2.properties.BooleanProperty())))\n",
+    "class NewObject2(object):\n",
+    "    pass\n",
+    "\n",
+    "\n",
+    "# Make my custom observable available in STIX 2.1\n",
+    "@stix2.v21.observables.CustomObservable('x-new-object-type',\n",
+    "                                    ((\"prop\", stix2.properties.BooleanProperty())))\n",
+    "class NewObject2(object):\n",
+    "    pass"
+   ]
+  }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

docs/ts_support.rst

@@ -112,20 +112,23 @@ How will custom work
 
 CustomObjects, CustomObservable, CustomMarking and CustomExtensions must be
 registered explicitly by STIX version. This is a design decision since properties
-or requirements may chance as the STIX Technical Specification advances.
+or requirements may change as the STIX Technical Specification advances.
 
 You can perform this by,
 
 .. code:: python
 
+    import stix2
+
     # Make my custom observable available in STIX 2.0
     @stix2.v20.observables.CustomObservable('x-new-object-type',
                                         (("prop", stix2.properties.BooleanProperty())))
-        class NewObject2(object):
+    class NewObject2(object):
-            pass
+        pass
+
 
     # Make my custom observable available in STIX 2.1
     @stix2.v21.observables.CustomObservable('x-new-object-type',
                                         (("prop", stix2.properties.BooleanProperty())))
-        class NewObject2(object):
+    class NewObject2(object):
-            pass
+        pass

setup.py

@@ -45,7 +45,7 @@ setup(
         'Programming Language :: Python :: 3.6',
     ],
     keywords="stix stix2 json cti cyber threat intelligence",
-    packages=find_packages(),
+    packages=find_packages(exclude=['*.test']),
     install_requires=[
         'python-dateutil',
         'pytz',