A small step toward modernizing ORM docs

(as described in issue 7659)

Change-Id: I37cf4899721092c5714ed5af4cb8617b06dcd236

diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst
index eab49f40cace2e1cd85546f8807e8b4a5e79482b..1f83fee50fde8090829a5f72b6e06bee73bb4ba6 100644 (file)
--- a/doc/build/orm/cascades.rst
+++ b/doc/build/orm/cascades.rst
@@ -107,7 +107,7 @@ so that the flush process may handle that related object appropriately.
 This case usually only arises if an object is removed from one :class:`.Session`
 and added to another::
 
-    >>> user1 = sess1.query(User).filter_by(id=1).first()
+    >>> user1 = sess1.scalars(select(User).filter_by(id=1)).first()
     >>> address1 = user1.addresses[0]
     >>> sess1.close()   # user1, address1 no longer associated with sess1
     >>> user1.addresses.remove(address1)  # address1 no longer associated with user1
@@ -141,7 +141,7 @@ with ``delete`` cascade configured::
 If using the above mapping, we have a ``User`` object and two
 related ``Address`` objects::
 
-    >>> user1 = sess.query(User).filter_by(id=1).first()
+    >>> user1 = sess1.scalars(select(User).filter_by(id=1)).first()
     >>> address1, address2 = user1.addresses
 
 If we mark ``user1`` for deletion, after the flush operation proceeds,

diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index 96408919762e390385dca75c3330e22113be6e29..716fea74e34a4b512443526816befb3da4d6a3c3 100644 (file)
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -52,7 +52,7 @@ offsets, either explicitly or via array slices::
 
         posts = relationship(Post, lazy="dynamic")
 
-    jack = session.query(User).get(id)
+    jack = session.get(User, id)
 
     # filter Jack's blog posts
     posts = jack.posts.filter(Post.headline=='this is a post')

diff --git a/doc/build/orm/composites.rst b/doc/build/orm/composites.rst
index 463bb70bc33e15d5e3eb512111857990c2a5852d..4e533f7cf7cef79370e36041269d5fc00f808593 100644 (file)
--- a/doc/build/orm/composites.rst
+++ b/doc/build/orm/composites.rst
@@ -50,7 +50,7 @@ attributes that will represent sets of columns via the ``Point`` class::
 
     from sqlalchemy import Column, Integer
     from sqlalchemy.orm import composite
-    from sqlalchemy.ext.declarative import declarative_base
+    from sqlalchemy.orm import declarative_base
 
     Base = declarative_base()
 
@@ -81,20 +81,15 @@ using the ``.start`` and ``.end`` attributes against ad-hoc ``Point`` instances:
 
     >>> v = Vertex(start=Point(3, 4), end=Point(5, 6))
     >>> session.add(v)
-    >>> q = session.query(Vertex).filter(Vertex.start == Point(3, 4))
-    {sql}>>> print(q.first().start)
+    >>> q = select(Vertex).filter(Vertex.start == Point(3, 4))
+    {sql}>>> print(session.scalars(q).first().start)
     BEGIN (implicit)
     INSERT INTO vertices (x1, y1, x2, y2) VALUES (?, ?, ?, ?)
-    (3, 4, 5, 6)
-    SELECT vertices.id AS vertices_id,
-            vertices.x1 AS vertices_x1,
-            vertices.y1 AS vertices_y1,
-            vertices.x2 AS vertices_x2,
-            vertices.y2 AS vertices_y2
+    [generated in ...] (3, 4, 5, 6)
+    SELECT vertices.id, vertices.x1, vertices.y1, vertices.x2, vertices.y2
     FROM vertices
     WHERE vertices.x1 = ? AND vertices.y1 = ?
-     LIMIT ? OFFSET ?
-    (3, 4, 1, 0)
+    [generated in ...] (3, 4)
     {stop}Point(x=3, y=4)
 
 .. autofunction:: composite
@@ -214,7 +209,11 @@ We can then use the above mapping as::
     s.add(hv)
     s.commit()
 
-    hv = s.query(HasVertex).filter(
-        HasVertex.vertex == Vertex(Point(1, 2), Point(3, 4))).first()
+    hv = s.scalars(
+        select(HasVertex).filter(
+            HasVertex.vertex == Vertex(Point(1, 2), Point(3, 4))
+        )
+    ).first()
     print(hv.vertex.start)
     print(hv.vertex.end)
+

diff --git a/doc/build/orm/contextual.rst b/doc/build/orm/contextual.rst
index eafdee427661377467f11c37e9a0fea9c4935b0e..5cd2ab441376023074d30febd3ae24de66f4f352 100644 (file)
--- a/doc/build/orm/contextual.rst
+++ b/doc/build/orm/contextual.rst
@@ -111,9 +111,9 @@ underlying :class:`.Session` being maintained by the registry::
     # equivalent to:
     #
     # session = Session()
-    # print(session.query(MyClass).all())
+    # print(session.scalars(select(MyClass)).all())
     #
-    print(Session.query(MyClass).all())
+    print(Session.scalars(select(MyClass)).all())
 
 The above code accomplishes the same task as that of acquiring the current
 :class:`.Session` by calling upon the registry, then using that :class:`.Session`.
@@ -195,7 +195,7 @@ diagram below illustrates this flow::
                                              # be used at any time, creating the
                                              # request-local Session() if not present,
                                              # or returning the existing one
-                                             Session.query(MyClass) # ...
+                                             Session.execute(select(MyClass)) # ...
 
                                              Session.add(some_object) # ...
 

diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst
index cb3ccfd8d297ebc1bbe897e0210220a5c3440a08..4d4455b6705e5e5259cbc6f015e71d17ba7bf5b2 100644 (file)
--- a/doc/build/orm/inheritance.rst
+++ b/doc/build/orm/inheritance.rst
@@ -648,20 +648,20 @@ Upon select, the polymorphic union produces a query like this:
 
 .. sourcecode:: python+sql
 
-    session.query(Employee).all()
+    session.scalars(select(Employee)).all()
     {opensql}
     SELECT
-        pjoin.id AS pjoin_id,
-        pjoin.name AS pjoin_name,
-        pjoin.type AS pjoin_type,
-        pjoin.manager_data AS pjoin_manager_data,
-        pjoin.engineer_info AS pjoin_engineer_info
+        pjoin.id,
+        pjoin.name,
+        pjoin.type,
+        pjoin.manager_data,
+        pjoin.engineer_info
     FROM (
         SELECT
             employee.id AS id,
             employee.name AS name,
-            CAST(NULL AS VARCHAR(50)) AS manager_data,
-            CAST(NULL AS VARCHAR(50)) AS engineer_info,
+            CAST(NULL AS VARCHAR(40)) AS manager_data,
+            CAST(NULL AS VARCHAR(40)) AS engineer_info,
             'employee' AS type
         FROM employee
         UNION ALL
@@ -669,14 +669,14 @@ Upon select, the polymorphic union produces a query like this:
             manager.id AS id,
             manager.name AS name,
             manager.manager_data AS manager_data,
-            CAST(NULL AS VARCHAR(50)) AS engineer_info,
+            CAST(NULL AS VARCHAR(40)) AS engineer_info,
             'manager' AS type
         FROM manager
         UNION ALL
         SELECT
             engineer.id AS id,
             engineer.name AS name,
-            CAST(NULL AS VARCHAR(50)) AS manager_data,
+            CAST(NULL AS VARCHAR(40)) AS manager_data,
             engineer.engineer_info AS engineer_info,
             'engineer' AS type
         FROM engineer
@@ -726,7 +726,7 @@ base class with the ``__abstract__`` indicator::
 Above, we are not actually making use of SQLAlchemy's inheritance mapping
 facilities; we can load and persist instances of ``Manager`` and ``Engineer``
 normally.   The situation changes however when we need to **query polymorphically**,
-that is, we'd like to emit ``session.query(Employee)`` and get back a collection
+that is, we'd like to emit ``select(Employee)`` and get back a collection
 of ``Manager`` and ``Engineer`` instances.    This brings us back into the
 domain of concrete inheritance, and we must build a special mapper against
 ``Employee`` in order to achieve this.