From: Gord Thompson Date: Sun, 20 Feb 2022 22:02:53 +0000 (-0700) Subject: A small step toward modernizing ORM docs X-Git-Tag: rel_2_0_0b1~473 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e246548cd80a2a423c6041ac05ae6521d1c20b46;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 eab49f40ca..1f83fee50f 100644 --- 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 9640891976..716fea74e3 100644 --- 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 463bb70bc3..4e533f7cf7 100644 --- 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 eafdee4276..5cd2ab4413 100644 --- 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 cb3ccfd8d2..4d4455b670 100644 --- 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.