README.ipynb

{
 "metadata": {
  "kernelspec": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "display_name": "IPython (Python 2)",
   "language": "python",
   "name": "python2"
  },
  "name": "",
  "signature": "sha256:bb676e1979c5682cd06c69d3fa4260a7ad1674e51b18ac502d099f20f8557caa"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "python-modeled"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import modeled\n",
      "print(modeled.__version__) "
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "0.1\n"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(modeled.__description__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Universal data modeling for Python.\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "* Create [classes](#1.-Writing-modeled-classes)\n",
      "  with typed data [members](#Adding-modeled-members) in pythonic style.\n",
      "* Use typed containers.\n",
      "* Map modeled classes and their instances\n",
      "  to any kind of data storage, serialization, visualization or user interface\n",
      "  by using existing adapters or writing custom ones."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<https://bitbucket.org/userzimmermann/python-modeled>\n",
      "\n",
      "<https://github.com/userzimmermann/python-modeled>"
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "0. Setup"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "__Supported Python versions__:\n",
      "[2.7](http://docs.python.org/2.7),\n",
      "[3.3](http://docs.python.org/3.3),\n",
      "[3.4](http://docs.python.org/3.4)\n",
      "\n",
      "Just install the latest [release](https://pypi.python.org/pypi/modeled)\n",
      "with [pip](http://www.pip-installer.org).\n",
      "It automatically installs all requirements:\n",
      "\n",
      "    pip install modeled"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "modeled.__requires__"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 9,
       "text": [
        "six\n",
        "path.py>=7.0\n",
        "moretools>=0.1.5"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "1. Writing modeled classes"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "All Python classes are derived from `object`.\n",
      "Modeled classes are derived from `modeled.object`,\n",
      "which has a predefined `mobject` shortcut:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from modeled import mobject"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 10
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "class MClass(mobject):\n",
      "    # optional\n",
      "    class model:\n",
      "        name = 'NotMClass'\n",
      "\n",
      "        group__option = 'value'\n",
      "\n",
      "        class group:\n",
      "            other_option = 'other value'"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 11
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Adding modeled members"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Modeled members are the typed attributes of modeled objects.\n",
      "They are defined as modeled class attributes\n",
      "and connect to class instances via Python's descriptor mechanism.\n",
      "These member descriptors are instances of the `modeled.member` base class,\n",
      "which has a predefined `m` shortcut.\n",
      "Typed member subclasses are created by passing any type (class object)\n",
      "in `[...]` brackets to the member base class:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from modeled import mobject, m"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "class MClass(mobject):\n",
      "    some_int = m[int]\n",
      "    some_float = m[float]\n",
      "    some_string = m[str]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "These typed member suclasses are created only once for each given type.\n",
      "Modeled member descriptors are automatically instantiated\n",
      "by `modeled.object`'s metaclass.\n",
      "You can easily access these instances on modeled class level:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "MClass.some_int"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 6,
       "text": [
        "modeled.member[int]()"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "MClass.some_int.mtype"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 7,
       "text": [
        "int"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Manually instantiate a member descriptor for defining a default value\n",
      "or passing extra keyword arguments or options:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "class MClass(mobject):\n",
      "    some_int = m[int](4, name='not_some_int', group__option='value')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Other keyword arguments are:\n",
      "\n",
      "* `new=` Any callable object which will be called instead of member's data type\n",
      "  if setting a member value which is not an instance of data type.\n",
      "  Must return a data type instance.\n",
      "* `choices=` A sequence of allowed member values.\n",
      "* `changed=` A sequence of callback functions (any callable objects)\n",
      "  to be triggered after setting member values.\n",
      "  Get the modeled class instance as first and the value as second argument."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "When providing a default value, the data type can be omitted:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "m(4)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 10,
       "text": [
        "modeled.member[int](4)"
       ]
      }
     ],
     "prompt_number": 10
    }
   ],
   "metadata": {}
  }
 ]
}