CascaDict_tutorial.ipynb

{
 "metadata": {
  "name": "",
  "signature": "sha256:7e933e975cd8ea190e8c18d0bdcb2f70b956a95211461a54824f01228d69a4fc"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# CascaDict - cascading dictionary for Python\n",
      "\n",
      "This little class aims to solve just another almost nonexistent problem - handling of cascading properties. To describe it simply, CascaDict implements something like class inheritance, but on dictionary-key level. See the code:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from cascadict import CascaDict\n",
      "\n",
      "fruit_properties = CascaDict({'type':'fruit', 'taste':'sweet', 'color':\"I don't have any color, I'm an abstract concept!\"})\n",
      "blueberry = fruit_properties.cascade({'name': 'blueberry', 'color':'blue'})\n",
      "\n",
      "print(blueberry['color'])\n",
      "print(blueberry['taste'])"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "blue\n",
        "sweet\n"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Internally, it's not just copy and append, one can also access all the cascaded values:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(blueberry.get_cascaded('color'))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "['blue', \"I don't have any color, I'm an abstract concept!\"]\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Cascaded ancestors are referenced, not copied:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "fruit_properties['taste'] = 'bittersweet'\n",
      "blueberry['taste']"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 3,
       "text": [
        "'bittersweet'"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "CascaDicts can be nested, and any dict element put into CascaDict is also nested as CascaDict:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "fruit_properties['classification'] = {'kingdom': 'Plantae',}\n",
      "blueberry['classification'] = {'Order': 'Ericales', 'Family': 'Ericaceae', 'Genus': 'Vaccinium', 'Section': 'Cyanococcus'}\n",
      "\n",
      "blueberry['classification']['kingdom']"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 4,
       "text": [
        "'Plantae'"
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "CascaDicts are of course iterable..."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "for key, value in blueberry.items():\n",
      "    print(key,value)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "('color', 'blue')\n",
        "('name', 'blueberry')\n",
        "('classification', <{'Section': 'Cyanococcus', 'Genus': 'Vaccinium', 'Order': 'Ericales', 'Family': 'Ericaceae'}, Ancestor: <{}, Ancestor: <{'kingdom': 'Plantae'}, Ancestor: None>>>)\n",
        "('taste', 'bittersweet')\n",
        "('type', 'fruit')\n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "... and picklable"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import pickle\n",
      "blueberry_jam = pickle.loads(pickle.dumps(blueberry))\n",
      "for key, value in blueberry_jam.items():\n",
      "    print(key,value)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "('color', 'blue')\n",
        "('name', 'blueberry')\n",
        "('classification', <{'Section': 'Cyanococcus', 'Genus': 'Vaccinium', 'Order': 'Ericales', 'Family': 'Ericaceae'}, Ancestor: <{}, Ancestor: <{'kingdom': 'Plantae'}, Ancestor: None>>>)\n",
        "('taste', 'bittersweet')\n",
        "('type', 'fruit')\n"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If needed, CascaDict can be \"flattened\" into normal (nested) dict:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "blueberry.copy_flat()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 7,
       "text": [
        "{'classification': {'Family': 'Ericaceae',\n",
        "  'Genus': 'Vaccinium',\n",
        "  'Order': 'Ericales',\n",
        "  'Section': 'Cyanococcus',\n",
        "  'kingdom': 'Plantae'},\n",
        " 'color': 'blue',\n",
        " 'name': 'blueberry',\n",
        " 'taste': 'bittersweet',\n",
        " 'type': 'fruit'}"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Or only the top (final) level of CascaDict, without any ancestor properties, can be copied:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "blueberry.copy_flat(level='skim')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 8,
       "text": [
        "{'classification': {'Family': 'Ericaceae',\n",
        "  'Genus': 'Vaccinium',\n",
        "  'Order': 'Ericales',\n",
        "  'Section': 'Cyanococcus'},\n",
        " 'color': 'blue',\n",
        " 'name': 'blueberry'}"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Combined with (e.g.) yaml, it makes any configuration processing a breeze:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import yaml\n",
      "\n",
      "config = '''\n",
      "defaults:\n",
      "    port: 5556\n",
      "    login_required: True\n",
      "    logging: \n",
      "        level: DEBUG\n",
      "        handler: stream\n",
      "        \n",
      "process_1:\n",
      "    max_runtime: 100\n",
      "    login_required: False\n",
      "    logging:\n",
      "        handler: file\n",
      "    \n",
      "process_2:\n",
      "    port: 6005\n",
      "    halt_on_error: True\n",
      "    logging:\n",
      "        level: ERROR\n",
      "\n",
      "'''\n",
      "\n",
      "raw_config = yaml.load(config)\n",
      "defaults = CascaDict(raw_config.pop('defaults'))\n",
      "properties = {} #no dict comprehension, remember Python 2.7 folk\n",
      "for k,v in raw_config.items():\n",
      "    properties[k] = CascaDict(v, ancestor=defaults)\n",
      "    \n",
      "for k,v in properties.items():\n",
      "    print(\"{0}: {1}\".format(k, v.copy_flat()))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "process_2: {'login_required': True, 'logging': {'handler': 'stream', 'level': 'ERROR'}, 'port': 6005, 'halt_on_error': True}\n",
        "process_1: {'logging': {'handler': 'file', 'level': 'DEBUG'}, 'login_required': False, 'max_runtime': 100, 'port': 5556}\n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## That's it\n",
      "\n",
      "This whole thing is just one small file, works in both Python 2.7 and 3.x and is released under [MIT License](https://opensource.org/licenses/MIT). Now, cascade!"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}