add faq notebook

 with initial django model example

README.md

@@ -1244,6 +1244,7 @@ class VerboseMachine(Machine):
 ### <a name="bug-reports"></a>I have a [bug report/issue/question]...
 For bug reports and other issues, please open an issue on GitHub.
 
-For usage questions, post on Stack Overflow, making sure to tag your question with the `transitions` and `python` tags.
+For usage questions, post on Stack Overflow, making sure to tag your question with the `transitions` and `python` tags. Do not forget to have a look at the [extended examples](./examples)!
+
 
 For any other questions, solicitations, or large unrestricted monetary gifts, email [Tal Yarkoni](mailto:[email protected]).

examples/Frequently asked questions.ipynb

@@ -0,0 +1,91 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Frequently asked questions\n",
+    "\n",
+    "* [How to use transitions with django models?](#How-to-use-transitions-with-django-models?)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### How to use `transitions` with django models?\n",
+    "\n",
+    "In [this comment](https://github.com/pytransitions/transitions/issues/146#issuecomment-300277397) **proofit404** provided a nice example about how to use `transitions` and django together:\n",
+    "\n",
+    "```python\n",
+    "from django.db import models\n",
+    "from django.db.models.signals import post_init\n",
+    "from django.dispatch import receiver\n",
+    "from django.utils.translation import ugettext_lazy as _\n",
+    "from transitions import Machine\n",
+    "\n",
+    "\n",
+    "class ModelWithState(models.Model):\n",
+    "    ASLEEP = 'asleep'\n",
+    "    HANGING_OUT = 'hanging out'\n",
+    "    HUNGRY = 'hungry'\n",
+    "    SWEATY = 'sweaty'\n",
+    "    SAVING_THE_WORLD = 'saving the world'\n",
+    "    STATE_TYPES = [\n",
+    "        (ASLEEP, _('asleep')),\n",
+    "        (HANGING_OUT, _('hanging out')),\n",
+    "        (HUNGRY, _('hungry')),\n",
+    "        (SWEATY, _('sweaty')),\n",
+    "        (SAVING_THE_WORLD, _('saving the world')),\n",
+    "    ]\n",
+    "    state = models.CharField(\n",
+    "        _('state'),\n",
+    "        max_length=100,\n",
+    "        choices=STATE_TYPES,\n",
+    "        default=ASLEEP,\n",
+    "        help_text=_('actual state'),\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "@receiver(post_init, sender=ModelWithState)\n",
+    "def init_state_machine(instance, **kwargs):\n",
+    "\n",
+    "    states = [state for state, _ in instance.STATE_TYPES]\n",
+    "    machine = instance.machine = Machine(model=instance, states=states, initial=instance.state)\n",
+    "    machine.add_transition('work_out', instance.HANGING_OUT, instance.HUNGRY)\n",
+    "    machine.add_transition('eat', instance.HUNGRY, instance.HANGING_OUT)\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}