Consider aliased=True, from_joinpoint as legacy

For a 1.4 / 1.3 merge, rewrite the documentation for
Query.join() to indicate calling forms that are now considered
legacy, including the use of strings in join(), sending a
series of join paths in one call, and using the aliased=True
flag.   update the elementtree examples as well to use aliased()
(they are much simpler to understand this way too) and update
other links.

Also improve docs for aliased() and some other ORM targets
such as PropComparator.

Change-Id: I636e3a9130dc5509e51c2cf60a52f38fcadffbc6
References: #4705

1 files changed, 32 insertions, 17 deletions

diff --git a/examples/elementtree/adjacency_list.py b/examples/elementtree/adjacency_list.py
index 0a5a922d0..cee73bffd 100644
--- a/examples/elementtree/adjacency_list.py
+++ b/examples/elementtree/adjacency_list.py
@@ -33,6 +33,7 @@ from sqlalchemy import MetaData
 from sqlalchemy import String
 from sqlalchemy import Table
 from sqlalchemy import Unicode
+from sqlalchemy.orm import aliased
 from sqlalchemy.orm import lazyload
 from sqlalchemy.orm import mapper
 from sqlalchemy.orm import relationship
@@ -215,14 +216,20 @@ ElementTree.dump(document.element)
 # PART VI - Searching for Paths
 
 # manually search for a document which contains "/somefile/header/field1:hi"
+root = aliased(_Node)
+child_node = aliased(_Node)
+grandchild_node = aliased(_Node)
+
 d = (
     session.query(Document)
-    .join("_root", aliased=True)
-    .filter(_Node.tag == "somefile")
-    .join("children", aliased=True, from_joinpoint=True)
-    .filter(_Node.tag == "header")
-    .join("children", aliased=True, from_joinpoint=True)
-    .filter(and_(_Node.tag == "field1", _Node.text == "hi"))
+    .join(Document._root.of_type(root))
+    .filter(root.tag == "somefile")
+    .join(root.children.of_type(child_node))
+    .filter(child_node.tag == "header")
+    .join(child_node.children.of_type(grandchild_node))
+    .filter(
+        and_(grandchild_node.tag == "field1", grandchild_node.text == "hi")
+    )
     .one()
 )
 ElementTree.dump(d.element)
@@ -232,31 +239,39 @@ ElementTree.dump(d.element)
 
 def find_document(path, compareto):
     query = session.query(Document)
-    attribute = "_root"
+    attribute = Document._root
     for i, match in enumerate(
         re.finditer(r"/([\w_]+)(?:\[@([\w_]+)(?:=(.*))?\])?", path)
     ):
         (token, attrname, attrvalue) = match.group(1, 2, 3)
-        query = query.join(
-            attribute, aliased=True, from_joinpoint=True
-        ).filter(_Node.tag == token)
-        attribute = "children"
+        target_node = aliased(_Node)
+
+        query = query.join(attribute.of_type(target_node)).filter(
+            target_node.tag == token
+        )
+
+        attribute = target_node.children
+
         if attrname:
+            attribute_entity = aliased(_Attribute)
+
             if attrvalue:
                 query = query.join(
-                    "attributes", aliased=True, from_joinpoint=True
+                    target_node.attributes.of_type(attribute_entity)
                 ).filter(
                     and_(
-                        _Attribute.name == attrname,
-                        _Attribute.value == attrvalue,
+                        attribute_entity.name == attrname,
+                        attribute_entity.value == attrvalue,
                     )
                 )
             else:
                 query = query.join(
-                    "attributes", aliased=True, from_joinpoint=True
-                ).filter(_Attribute.name == attrname)
+                    target_node.attributes.of_type(attribute_entity)
+                ).filter(attribute_entity.name == attrname)
     return (
-        query.options(lazyload("_root")).filter(_Node.text == compareto).all()
+        query.options(lazyload(Document._root))
+        .filter(target_node.text == compareto)
+        .all()
     )