From: Mike Bayer Date: Wed, 8 Mar 2023 15:10:14 +0000 (-0500) Subject: additional consistency for ORM/Core in tutorial X-Git-Tag: rel_1_4_47~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=807650daa95d8d6ec77b17e2cffcdf47884e1e90;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git additional consistency for ORM/Core in tutorial * Make sure we have blue borders for all sections * rewrite "blue border" text, refer to textual means of determining subject matter for a section; "blue borders" are not a primary source of information * Add some more intro text that was missing Change-Id: I4d599e13d23bad8bb3c199a11afb53e3e9100c59 References: #9450 (cherry picked from commit 8d5986fafd8360ddfe3992bd56602d5a52a23392) --- diff --git a/doc/build/tutorial/data.rst b/doc/build/tutorial/data.rst index 1d5dde7b84..3242710a92 100644 --- a/doc/build/tutorial/data.rst +++ b/doc/build/tutorial/data.rst @@ -5,6 +5,8 @@ .. include:: tutorial_nav_include.rst +.. rst-class:: core-header, orm-addin + .. _tutorial_working_with_data: Working with Data diff --git a/doc/build/tutorial/data_insert.rst b/doc/build/tutorial/data_insert.rst index 0d745cb319..765b6890b6 100644 --- a/doc/build/tutorial/data_insert.rst +++ b/doc/build/tutorial/data_insert.rst @@ -5,9 +5,7 @@ .. include:: tutorial_nav_include.rst - -.. rst-class:: core-header - +.. rst-class:: core-header, orm-addin .. _tutorial_core_insert: diff --git a/doc/build/tutorial/engine.rst b/doc/build/tutorial/engine.rst index fc8973c465..4e53ae6bf9 100644 --- a/doc/build/tutorial/engine.rst +++ b/doc/build/tutorial/engine.rst @@ -3,11 +3,19 @@ .. include:: tutorial_nav_include.rst +.. rst-class:: core-header, orm-addin + .. _tutorial_engine: Establishing Connectivity - the Engine ========================================== +.. container:: orm-header + + **Welcome ORM and Core readers alike!** + + Every SQLAlchemy application that connects to a database needs to use + an :class:`_engine.Engine`. This short section is for everyone. The start of any SQLAlchemy application is an object called the :class:`_future.Engine`. This object acts as a central source of connections diff --git a/doc/build/tutorial/index.rst b/doc/build/tutorial/index.rst index cb6c2feae3..2440a33ed0 100644 --- a/doc/build/tutorial/index.rst +++ b/doc/build/tutorial/index.rst @@ -42,9 +42,14 @@ These APIs are known as **Core** and **ORM**. to a database, interacting with database queries and results, and programmatic construction of SQL statements. - Sections that have a **dark blue border on the right** will discuss - concepts that are **primarily Core-only**; when using the ORM, these - concepts are still in play but are less often explicit in user code. + Sections that are **primarily Core-only** will not refer to the ORM. + SQLAlchemy constructs used in these sections will be imported from the + ``sqlalchemy`` namespace. As an additional indicator of subject + classification, they will also include a **dark blue border on the right**. + When using the ORM, these concepts are still in play but are less often + explicit in user code. ORM users should read these sections, but not expect + to be using these APIs directly for ORM-centric code. + .. container:: orm-header @@ -56,14 +61,28 @@ These APIs are known as **Core** and **ORM**. SQL Expression Language to allow SQL queries to be composed and invoked in terms of user-defined objects. - Sections that have a **light blue border on the left** will discuss - concepts that are **primarily ORM-only**. Core-only users - can skip these. + Sections that are **primarily ORM-only** should be **titled to + include the phrase "ORM"**, so that it's clear this is an ORM related topic. + SQLAlchemy constructs used in these sections will be imported from the + ``sqlalchemy.orm`` namespace. Finally, as an additional indicator of + subject classification, they will also include a **light blue border on the + left**. Core-only users can skip these. .. container:: core-header, orm-dependency - A section that has **both light and dark borders on both sides** will - discuss a **Core concept that is also used explicitly with the ORM**. + **Most** sections in this tutorial discuss **Core concepts that + are also used explicitly with the ORM**. SQLAlchemy 2.0 in particular + features a much greater level of integration of Core API use within the + ORM. + + For each of these sections, there will be **introductory text** discussing the + degree to which ORM users should expect to be using these programming + patterns. SQLAlchemy constructs in these sections will be imported from the + ``sqlalchemy`` namespace with some potential use of ``sqlalchemy.orm`` + constructs at the same time. As an additional indicator of subject + classification, these sections will also include **both a thinner light + border on the left, and a thicker dark border on the right**. Core and ORM + users should familiarize with concepts in these sections equally. Tutorial Overview diff --git a/doc/build/tutorial/orm_related_objects.rst b/doc/build/tutorial/orm_related_objects.rst index 02ff2c1722..61ce5a1bd6 100644 --- a/doc/build/tutorial/orm_related_objects.rst +++ b/doc/build/tutorial/orm_related_objects.rst @@ -5,11 +5,12 @@ .. include:: tutorial_nav_include.rst +.. rst-class:: orm-header .. _tutorial_orm_related_objects: -Working with Related Objects -============================ +Working with ORM Related Objects +================================ In this section, we will cover one more essential ORM concept, which is how the ORM interacts with mapped classes that refer to other objects. In the