Merge branch 'release/v0.1'

.gitignore

@@ -2,6 +2,7 @@
 *.pyc
 *.egg-info
 __pycache__
+.ipynb_checkpoints
 
 # Temporary OS files
 Icon*

CHANGES.md

@@ -1,7 +1,7 @@
 Changelog
 =========
 
-0.0.0 (2013/10/09)
-------------------
+0.1 (2014-09-29)
+----------------
 
- - <Change the version, date, and this text.>
+ - Initial release.

Makefile

@@ -7,7 +7,7 @@ ifndef TEST_RUNNER
 	# options are: nose, pytest
 	TEST_RUNNER := pytest
 endif
-UNIT_TEST_COVERAGE := 92
+UNIT_TEST_COVERAGE := 94
 INTEGRATION_TEST_COVERAGE := 100
 
 # Project settings (automatically detected from files/directories)
@@ -74,6 +74,17 @@ $(ALL): $(SOURCES)
 .PHONY: ci
 ci: pep8 pep257 test tests
 
+.PHONY: demo
+demo: env
+	$(PIP) install --upgrade ipython[notebook]
+	cd examples/students; $(OPEN) .
+	$(BIN)/ipython notebook examples/demo.ipynb
+
+.PHONY: reset
+reset:
+	rm -rf examples/*/*.yml
+	git checkout examples/*.ipynb
+
 # Development Installation ###################################################
 
 .PHONY: env
@@ -99,7 +110,7 @@ $(DEPENDS_CI): Makefile
 .PHONY: .depends-dev
 .depends-dev: env Makefile $(DEPENDS_DEV)
 $(DEPENDS_DEV): Makefile
-	$(PIP) install --upgrade pep8radius docutils pdoc pylint wheel
+	$(PIP) install --upgrade pep8radius pygments docutils pdoc pylint wheel
 	touch $(DEPENDS_DEV)  # flag to indicate dependencies are installed
 
 # Documentation ##############################################################

README.md

@@ -9,6 +9,12 @@ YORM
 
 YORM provides functions and decorators to enable automatic, bidirectional, and human-friendly mappings of Python object attributes to YAML files.
 
+Uses beyond typical object serialization and object mapping include:
+
+* automatic bidirectional conversion of attributes types
+* attribute creation and type inference for new attributes
+* storage of content in text files optimized for version control
+* custom converters to map complex classes to JSON-compatible types
 
 
 Getting Started
@@ -19,11 +25,10 @@ Requirements
 
 * Python 3.3+
 
-
 Installation
 ------------
 
-YORM can be installed with 'pip':
+YORM can be installed with pip:
 
     $ pip install YORM
 
@@ -33,20 +38,69 @@ Or directly from the source code:
     $ cd yorm
     $ python setup.py install
 
-
-
 Basic Usage
 ===========
 
-After installation, YORM can be imported from the package:
+Simply take an existing class:
+
+```python
+class Student:
+
+    def __init__(name, school, number, year=2009):
+        self.name = name
+        self.school = school
+        self.number = number
+        self.year = year
+        self.gpa = 0.0
+```
+
+and define an attribute mapping:
 
-    $ python
-    >>> import yorm
-    yorm.__version__
+```python
+from yorm import store_instances, map_attr
+from yorm.standard import 
 
-YORM doesn't do anything yet.
+@map_attr(name=String, year=Integer, gpa=Float)
+@store_instances("students/{self.school}/{self.number}.yml")
+class Student: ...
+```
 
+Modifications to an object's mapped attributes:
 
+```python
+>>> s1 = Student("John Doe", "GVSU", 123)
+>>> s2 = Student("Jane Doe", "GVSU", 456, year=2014)
+>>> s1.gpa = 3
+```
+
+are automatically reflected on the filesytem:
+
+```bash
+$ cat students/GVSU/123.yml
+name: John Doe
+gpa: 3.0
+school: GVSU
+year: 2009
+```
+
+Modifications and new content in the mapped file:
+
+```bash
+$ echo "name: John Doe
+> gpa: 1.8
+> year: 2010
+> expelled: true
+" > students/GVSU/123.yml
+```
+
+are automatically reflected in the objects:
+
+```python
+>>> s1.gpa
+1.8
+>>> s1.expelled
+True
+```
 
 For Contributors
 ================
@@ -62,7 +116,6 @@ Requirements
 * Pandoc: http://johnmacfarlane.net/pandoc/installing.html
 * Graphviz: http://www.graphviz.org/Download.php
 
-
 Installation
 ------------
 

examples/demo.ipynb

@@ -0,0 +1,93 @@
+{
+ "metadata": {
+  "name": "",
+  "signature": "sha256:843b0edc033d9630b37ca635827d82dc27dbf596805ff39df082b65a22d02f3a"
+ },
+ "nbformat": 3,
+ "nbformat_minor": 0,
+ "worksheets": [
+  {
+   "cells": [
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "import logging\n",
+      "logger = logging.getLogger()\n",
+      "logger.setLevel(logging.DEBUG-1)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "import yorm"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "class Student:\n",
+      "    \n",
+      "    def __init__(self, name, number, graduated=False):\n",
+      "        self.name = name\n",
+      "        self.number = number\n",
+      "        self.graduated = graduated\n",
+      "        \n",
+      "    def __repr__(self):\n",
+      "        return \"<student {}>\".format(self.number)\n",
+      "        \n",
+      "    def graduate(self):\n",
+      "        self.graduated = True"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "@yorm.map_attr(name=yorm.standard.String)\n",
+      "@yorm.map_attr(graduated=yorm.standard.Boolean)\n",
+      "@yorm.store_instances(\"students/{n}.yml\", {'n': 'number'})\n",
+      "class MappedStudent(Student):\n",
+      "    \n",
+      "    pass"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "s1 = MappedStudent(\"John Doe\", 123)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "s2 = MappedStudent(\"Jane Doe\", 456, graduated=True)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    }
+   ],
+   "metadata": {}
+  }
+ ]
+}

examples/students/.gitignore

@@ -0,0 +1 @@
+*.yml

yorm/__init__.py

@@ -3,7 +3,7 @@
 """Package for YORM."""
 
 __project__ = 'YORM'
-__version__ = '0.0.0'
+__version__ = '0.1'
 
 VERSION = __project__ + '-' + __version__
 

yorm/base.py

@@ -15,18 +15,19 @@ def __getattribute__(self, name):
         if name in ('yorm_mapper', 'yorm_attrs'):
             return object.__getattribute__(self, name)
 
-        log.trace("getting attribute '{}'...".format(name))
-
-        if name in self.yorm_attrs:
+        try:
+            value = object.__getattribute__(self, name)
+        except AttributeError:
             self.yorm_mapper.retrieve(self)
+            value = object.__getattribute__(self, name)
         else:
-            log.trace("unmapped: {}".format(name))
+            if name in self.yorm_attrs:
+                self.yorm_mapper.retrieve(self)
+                value = object.__getattribute__(self, name)
 
-        return object.__getattribute__(self, name)
+        return value
 
     def __setattr__(self, name, value):
-        log.trace("setting attribute '{}' to {}...".format(name, repr(value)))
-
         if hasattr(self, 'yorm_attrs') and name in self.yorm_attrs:
             converter = self.yorm_attrs[name]
             value = converter.to_value(value)
@@ -38,8 +39,6 @@ def __setattr__(self, name, value):
                 self.yorm_mapper.store(self)
             else:
                 log.trace("automatic storage is off")
-        else:
-            log.trace("unmapped: {}".format(name))
 
     def __enter__(self):
         log.debug("turning off automatic storage...")
@@ -97,12 +96,12 @@ def to_value(cls, obj):  # pylint: disable=E0213
                 converter = yorm_attrs.pop(name)
             except KeyError:
                 from . import standard
-                converter = standard.match(name, data)
+                converter = standard.match(name, data, nested=True)
                 cls.yorm_attrs[name] = converter
             value[name] = converter.to_value(data)
 
         for name, converter in yorm_attrs.items():
-            log.debug("adding deleted '{}'...".format(name))
+            log.trace("adding missing nested key '{}'...".format(name))
             value[name] = converter.to_value(None)
 
         return value

yorm/common.py

@@ -77,7 +77,7 @@ def create_dirname(path):
     """Ensure a parent directory exists for a path."""
     dirpath = os.path.dirname(path)
     if dirpath and not os.path.isdir(dirpath):
-        log.trace("creating directory {}...".format(dirpath))
+        log.trace("creating directory '{}'...".format(dirpath))
         os.makedirs(dirpath)