update doc, add unit test for doc example.

Readme.rst

@@ -20,15 +20,44 @@ Usage
 
 and so forth.
 
-It's also possible to add kk.Tag objects directly to the tags
-property, but they'll be treated as strings.  To access the tag
-objects, do something like::
+This will generate tables like this::
+
+  foos: 
+     db_id
+         1
+
+  kk_tag_associations:
+     db_id  tag_id target_table  target_id
+         1       1         foos          1
+         2       2         foos          1
+         3       3         foos          1
+
+  kk_tags:
+     db_id  text
+         1  tag1
+         2  tag2
+         3  tag3
+
+To access the tags::
+
+  for i in a.tags:
+      print(i)
+
+  tag1
+  tag2
+  tag3
+
+The tags member gives you a list of tag strings.  To access the tag
+objects, iterate the kk_tag_associations member::
 
   return [ta.tag_obj for ta in a.kk_tag_associations]
 
 This will bypass the association proxy and return a list of Tag
 objects.
 
+It's also possible to add kk.Tag objects directly to the tags
+property on a taggable object, and they'll be handled correctly.  
+
 
 Design considerations
 ---------------------

tests/test_basic.py

@@ -6,7 +6,9 @@ import pandas as pd
 import pprint
 import sqlalchemy as sa
 import sqlite3
+import textwrap
 import unittest
+
 import libkosokoso as kk
 
 class Foo(kk.Taggable):
@@ -221,6 +223,42 @@ class ks_basic(unittest.TestCase):
         a.tags.extend(l2)
         self.assertEqual(l, a.tags)
 
+    def test_pretty(self):
+        """verify that the example in the readme works."""
+        a = Foo()
+        a.tags.append('tag1')
+        a.tags.extend(['tag2', 'tag3'])
+        self.session.add(a)
+        self.session.commit()
+
+        expected = textwrap.dedent("""
+                   db_id
+                0      1
+                   db_id  tag_id target_table  target_id
+                0      1       1         foos          1
+                1      2       2         foos          1
+                2      3       3         foos          1
+                   db_id  text
+                0      1  tag1
+                1      2  tag2
+                2      3  tag3
+                tag1
+                tag2
+                tag3"""
+        )
+
+        actual = []
+        actual.append(str(pd.read_sql_query("SELECT * FROM foos",
+            self.engine)))
+        actual.append(str(pd.read_sql_query("SELECT * FROM kk_tag_associations",
+            self.engine)))
+        actual.append(str(pd.read_sql_query("SELECT * FROM kk_tags",
+            self.engine)))
+        for i in a.tags:
+            actual.append(i)
+        actual = '\n'.join(actual)
+        self.assertEqual(expected, '\n%s' % actual)
+
     def test_addstring_repeated(self):
         a1 = Foo()
         a2 = Foo()