{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Quick Start\n",
    "===========\n",
    "\n",
    "Let's go through creating a `mincepy` compatible type and learn how to store, search for, annotate and get\n",
    "the history of objects stored in the database.\n",
    "\n",
    "Creating types\n",
    "--------------"
   ]
  },
  {
   "cell_type": "code",
   "source": [
    "import mincepy\n",
    "import uuid\n",
    "\n",
    "\n",
    "class Person(mincepy.SimpleSavable):\n",
    "    TYPE_ID = uuid.UUID('26798d9e-8c78-430a-ab2c-b17d612ef5fe')\n",
    "    ATTRS = ('name', 'age')\n",
    "\n",
    "    def __init__(self, name, age):\n",
    "        super().__init__()\n",
    "        self.name = name\n",
    "        self.age = age"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 1,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": [
    "Here, we've defined a simple object and told `mincepy`:\n",
    "\n",
    "1. that the attributes `name` and `age` should be stored when saving `Person` objects, and,\n",
    "2. that this type can be identified by the ID given in `TYPE_ID`"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Storing objects\n",
    "---------------\n",
    "\n",
    "Now, let's save some people!  First we get a historian which is responsible for keeping track of all\n",
    "object being saved and loaded:\n"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "historian = mincepy.create_historian('mongodb://127.0.0.1/mince-quick-start')\n",
    "mincepy.set_historian(historian) # Tell mincepy to use this as the default"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 2,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": [
    "Finally, we can instantiate and save some people!"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5e99d6451220e72072cc6996 5e99d6451220e72072cc6997\n"
     ]
    }
   ],
   "source": [
    "martin = Person('Martin', 34)\n",
    "martin_id = historian.save(martin)\n",
    "\n",
    "# Let's save a couple more\n",
    "sonia_id, upul_id = historian.save(Person('Sonia', 30), Person('Upul', 35))\n",
    "\n",
    "# With `SimpleSavable`s we can also do this:\n",
    "gavin = Person('Gavin', 34)\n",
    "gavin_id = gavin.save()\n",
    "\n",
    "print(martin_id, sonia_id)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Above, we see some of the IDs assigned to our objects.  These serve to uniquely identify them and can be used to load\n",
    "them from the database.\n",
    "\n",
    "Loading objects\n",
    "---------------\n",
    "\n",
    "Ok, now let's load."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Martin, 34\n"
     ]
    }
   ],
   "source": [
    "del martin\n",
    "\n",
    "martin, sonia = historian.load(martin_id, sonia_id)\n",
    "print(\"{}, {}\".format(martin.name, martin.age))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Finding objects\n",
    "---------------\n",
    "\n",
    "Now, let's do a search"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "source": [
    "for person in historian.find(Person, state=dict(age=34)):\n",
    "    print('{}, {}'.format(person.name, person.age))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 5,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Gavin, 34\n",
      "Martin, 34\n"
     ]
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "Modifying objects\n",
    "-----------------\n",
    "\n",
    "Simple, just mutate our object and save!"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "source": [
    "sonia.age = 31\n",
    "sonia.save()\n",
    "\n",
    "# Let's double check!\n",
    "del sonia\n",
    "sonia = historian.load(sonia_id)\n",
    "print(sonia.age)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 6,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "31\n"
     ]
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "Annotating objects\n",
    "------------------\n",
    "\n",
    "Objects can be annotated by setting a metadata dictionary."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'city': 'Glasgow'}\n"
     ]
    }
   ],
   "source": [
    "historian.meta.set(sonia, {'city': 'Copenhagen'})\n",
    "historian.meta.set(martin, {'city': 'Copenhagen'})\n",
    "historian.meta.set(gavin, {'city': 'Glasgow'})\n",
    "\n",
    "print(historian.meta.get(gavin))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "*Ok, that's cool so now what?*\n",
    "  \n",
    "Well, we can also search the metadata.\n",
    "\n",
    "Searching metadata\n",
    "------------------"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "for person in historian.find(Person, state=dict(age=34), meta=dict(city='Glasgow')):\n",
    "    print(\"{}, {}\".format(person.name, person.age))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 8,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Gavin, 34\n"
     ]
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "*Nice*.\n",
    "\n",
    "Indeed, have a look at [Historian.find()](../apidoc.rst#mincepy.Historian.find)\n",
    " for a full lowdown on how to find stuff.\n",
    "\n",
    "\n",
    "*So what else can I do?*\n",
    "\n",
    "How about looking into the past?\n",
    "\n",
    "Version control\n",
    "---------------"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "source": [
    "records = historian.history(sonia, as_objects=False)\n",
    "for record in records:\n",
    "    print(\"{}, {}\".format(record.version, record.state))\n",
    "\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 9,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0, {'name': 'Sonia', 'age': 30}\n",
      "1, {'name': 'Sonia', 'age': 31}\n"
     ]
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "Here we see two records that were fetched from the archive for Sonia.  One with the original age value and the other\n",
    "with the current.  MincePy will by default keep a record of any modifications you make to objects, think of as being\n",
    "like `git`, but for objects.  We can use a historical record to load the object as it was then:"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "source": [
    "past_sonia = historian.load(records[0].get_reference())\n",
    "print(\"{}, {}\".format(past_sonia.name, past_sonia.age))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 10,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Sonia, 30\n"
     ]
    }
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}