{
 "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",
    "    name = mincepy.field()\n",
    "    age = mincepy.field()"
   ],
   "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 need to connect to our MongoDB database:\n"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "historian = mincepy.connect('mongodb://127.0.0.1/mince-quick-start', use_globally=True)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "execution_count": 2,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": [
    "The `historian` is our connection the database and provides methods to perform database related actions on our objects.\n",
    "\n",
    "Now 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": [
      "5f75cf7b44703dcf435c8500 5f75cf7b44703dcf435c8501\n"
     ]
    }
   ],
   "source": [
    "martin = Person(name='Martin', age=34)\n",
    "martin_id = historian.save(martin)\n",
    "\n",
    "# Let's save a couple more\n",
    "sonia_id, upul_id = historian.save(\n",
    "    Person(name='Sonia', age=30), Person(name='Upul', age=35))\n",
    "\n",
    "# We can call .save() on the object as we have inherited from SimpleSavable\n",
    "gavin = Person(name='Gavin', age=34)\n",
    "gavin_id = gavin.save()\n",
    "\n",
    "print(martin_id, sonia_id)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Here 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",
    "Loading objects is as simple as:"
   ],
   "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.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": [
      "Martin, 34\n",
      "Gavin, 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, dict(city='Copenhagen'))\n",
    "# Can also do it like this:\n",
    "martin.set_meta(dict(city='Copenhagen'))\n",
    "gavin.set_meta(dict(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.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 = list(historian.snapshots.records.find(obj_id=sonia_id))\n",
    "for record in records:\n",
    "    print(\"{}, {}\".format(record.version, record.state))\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 = records[0].load()\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"
     ]
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "So, that gets you up to speed on the basics of using mincePy.\n",
    "Have a look at the [API reference](../apidoc.rst) and post an issue [here](https://github.com/muhrin/mincepy/issues>) if there is anything else you would like to see documented.\n",
    "\n",
    "\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "name": "pycharm-d5059434",
   "language": "python",
   "display_name": "PyCharm (mince)"
  },
  "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
}