- mega example cleanup

- added READMEs to all examples in each __init__.py and added to sphinx documentation
- added versioning example
- removed vertical/vertical.py, the dictlikes are more straightforward

4 files changed, 30 insertions, 29 deletions

diff --git a/examples/elementtree/__init__.py b/examples/elementtree/__init__.py
index e69de29bb..70554f5c9 100644
--- a/examples/elementtree/__init__.py
+++ b/examples/elementtree/__init__.py
@@ -0,0 +1,30 @@
+"""
+Illustrates three strategies for persisting and querying XML documents as represented by 
+ElementTree in a relational database.   The techniques do not apply any mappings to the ElementTree objects directly, so are compatible with the native cElementTree as well as lxml, and can be adapted to suit any kind of DOM representation system.   Querying along xpath-like strings is illustrated as well.
+
+In order of complexity:
+
+* ``pickle.py`` - Quick and dirty, serialize the whole DOM into a BLOB column.  While the example
+  is very brief, it has very limited functionality.
+* ``adjacency_list.py`` - Each DOM node is stored in an individual table row, with attributes
+  represented in a separate table.  The nodes are associated in a hierarchy using an adjacency list
+  structure.  A query function is introduced which can search for nodes along any path with a given
+  structure of attributes, basically a (very narrow) subset of xpath.
+* ``optimized_al.py`` - Uses the same strategy as ``adjacency_list.py``, but adds a
+  :class:`~sqlalchemy.orm.interfaces.MapperExtension` which optimizes how the hierarchical structure  
+  is loaded, such that the full set of DOM nodes are loaded within a single table result set, and
+  are organized hierarchically as they are received during a load.
+
+E.g.::
+    
+    # parse an XML file and persist in the database
+    doc = ElementTree.parse("test.xml")
+    session.add(Document(file, doc))
+    session.commit()
+    
+    # locate documents with a certain path/attribute structure 
+    for document in find_document('/somefile/header/field2[@attr=foo]'):
+        # dump the XML
+        print document
+    
+"""
\ No newline at end of file
diff --git a/examples/elementtree/adjacency_list.py b/examples/elementtree/adjacency_list.py
index 58156dcb6..d2151d6ef 100644
--- a/examples/elementtree/adjacency_list.py
+++ b/examples/elementtree/adjacency_list.py
@@ -13,16 +13,6 @@ from sqlalchemy.orm import mapper, relation, create_session, lazyload
 
 import sys, os, StringIO, re
 
-import logging
-logging.basicConfig()
-
-# uncomment to show SQL statements
-#logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
-
-# uncomment to show SQL statements and result sets
-#logging.getLogger('sqlalchemy.engine').setLevel(logging.DEBUG)
-
-
 from xml.etree import ElementTree
 
 meta = MetaData()
diff --git a/examples/elementtree/optimized_al.py b/examples/elementtree/optimized_al.py
index c03acee1d..dcc3c00ba 100644
--- a/examples/elementtree/optimized_al.py
+++ b/examples/elementtree/optimized_al.py
@@ -12,16 +12,6 @@ from sqlalchemy.orm import mapper, relation, create_session, lazyload
 
 import sys, os, StringIO, re
 
-import logging
-logging.basicConfig()
-
-# uncomment to show SQL statements
-#logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
-
-# uncomment to show SQL statements and result sets
-#logging.getLogger('sqlalchemy.engine').setLevel(logging.DEBUG)
-
-
 from xml.etree import ElementTree
 
 meta = MetaData()
diff --git a/examples/elementtree/pickle.py b/examples/elementtree/pickle.py
index 2176512cf..4eaaa2f8d 100644
--- a/examples/elementtree/pickle.py
+++ b/examples/elementtree/pickle.py
@@ -12,15 +12,6 @@ from sqlalchemy.orm import mapper, create_session
 
 import sys, os
 
-import logging
-logging.basicConfig()
-
-# uncomment to show SQL statements
-#logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
-
-# uncomment to show SQL statements and result sets
-#logging.getLogger('sqlalchemy.engine').setLevel(logging.DEBUG)
-
 from xml.etree import ElementTree
 
 engine = create_engine('sqlite://')