From: Mike Bayer Date: Thu, 13 Oct 2022 14:13:01 +0000 (-0400) Subject: further 2.0 modernizations X-Git-Tag: rel_2_0_0b1~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=80372f6c4c2e7817a49c787d746aef8e5f99c7d8;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git further 2.0 modernizations biggest change here is the old tutorials were removed from the TOC and some additional links to them have been corrected. Change-Id: I79b878a946422eac24ed2449b440fc5d556576c4 --- diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index d092c70406..7b96c1df9a 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -77,8 +77,8 @@ any transactional state or locks are removed (this is known as Our example above illustrated the execution of a textual SQL string, which should be invoked by using the :func:`_expression.text` construct to indicate that we'd like to use textual SQL. The :meth:`_engine.Connection.execute` method can of -course accommodate more than that, including the variety of SQL expression -constructs described in :ref:`sqlexpression_toplevel`. +course accommodate more than that; see :ref:`tutorial_working_with_data` +in the :ref:`unified_tutorial` for a tutorial. Using Transactions diff --git a/doc/build/core/expression_api.rst b/doc/build/core/expression_api.rst index 236e0e2ee7..96d5d5a89e 100644 --- a/doc/build/core/expression_api.rst +++ b/doc/build/core/expression_api.rst @@ -5,8 +5,9 @@ SQL Statements and Expressions API .. module:: sqlalchemy.sql.expression -This section presents the API reference for the SQL Expression Language. For a full introduction to its usage, -see :ref:`sqlexpression_toplevel`. +This section presents the API reference for the SQL Expression Language. +For an introduction, start with :ref:`tutorial_working_with_data` +in the :ref:`unified_tutorial`. .. toctree:: diff --git a/doc/build/core/future.rst b/doc/build/core/future.rst index 1174f7d0ac..9c171b9db5 100644 --- a/doc/build/core/future.rst +++ b/doc/build/core/future.rst @@ -1,22 +1,17 @@ -.. _core_future_toplevel: +:orphan: SQLAlchemy 2.0 Future (Core) ============================ -This package includes a relatively small number of transitional elements -to allow "2.0 mode" to take place within SQLAlchemy 1.4. +.. admonition:: We're 2.0! -In the 2.0 release of SQLAlchemy, the objects published here are the same -:class:`_engine.Engine`, :class:`_engine.Connection` and -:func:`_sa.create_engine` classes and functions that are -used by default. The package is here for backwards compatibility with -SQLAlchemy 1.4. + This page described the "future" mode provided in SQLAlchemy 1.4 + for the purposes of 1.4 -> 2.0 transition. For 2.0, the "future" + parameter on :func:`_sa.create_engine` and :class:`_orm.Session` + continues to remain available for backwards-compatibility support, however + if specified must be left at the value of ``True``. -The ``sqlalchemy.future`` package will be deprecated in a subsequent -2.x release and eventually removed. - -.. seealso:: - - :ref:`migration_20_toplevel` - Introduction to the 2.0 series of SQLAlchemy + .. seealso:: + :ref:`migration_20_toplevel` - Introduction to the 2.0 series of SQLAlchemy diff --git a/doc/build/core/index.rst b/doc/build/core/index.rst index 08e4a5e061..764247ab56 100644 --- a/doc/build/core/index.rst +++ b/doc/build/core/index.rst @@ -16,9 +16,4 @@ Language provides a schema-centric usage paradigm. types engines_connections api_basics - future -.. toctree:: - :hidden: - - tutorial diff --git a/doc/build/core/selectable.rst b/doc/build/core/selectable.rst index 812f6f99a9..7537df7d56 100644 --- a/doc/build/core/selectable.rst +++ b/doc/build/core/selectable.rst @@ -1,11 +1,16 @@ -Selectables, Tables, FROM objects +SELECT and Related Constructs ================================= -The term "selectable" refers to any object that rows can be selected from; -in SQLAlchemy, these objects descend from :class:`_expression.FromClause` and their -distinguishing feature is their :attr:`_expression.FromClause.c` attribute, which is -a namespace of all the columns contained within the FROM clause (these -elements are themselves :class:`_expression.ColumnElement` subclasses). +The term "selectable" refers to any object that represents database rows. In +SQLAlchemy, these objects descend from :class:`_expression.Selectable`, the +most prominent being :class:`_expression.Select`, which represents a SQL SELECT +statement. A subset of :class:`_expression.Selectable` is +:class:`_expression.FromClause`, which represents objects that can be within +the FROM clause of a :class:`.Select` statement. A distinguishing feature of +:class:`_expression.FromClause` is the :attr:`_expression.FromClause.c` +attribute, which is a namespace of all the columns contained within the FROM +clause (these elements are themselves :class:`_expression.ColumnElement` +subclasses). .. currentmodule:: sqlalchemy.sql.expression diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index c9806ce62a..0efb56c263 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -1,4 +1,4 @@ -.. _sqlexpression_toplevel: +:orphan: ================================= SQL Expression Language Tutorial diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index 94e1ea023a..79de9026bc 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -237,7 +237,7 @@ My Query does not return the same number of objects as query.count() tells me - The :class:`_query.Query` object, when asked to return a list of ORM-mapped objects, will **deduplicate the objects based on primary key**. That is, if we -for example use the ``User`` mapping described at :ref:`ormtutorial_toplevel`, +for example use the ``User`` mapping described at :ref:`tutorial_orm_table_metadata`, and we had a SQL query like the following:: q = session.query(User).outerjoin(User.addresses).filter(User.name == "jack") diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 4baf6abcca..d0bc4f8148 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -19,7 +19,9 @@ Glossary throughout the 1.x series of SQLAlchemy and earlier (e.g. 1.3, 1.2, etc) and the term "2.0 style" refers to the way an API will look in version 2.0. Version 1.4 implements nearly all of 2.0's API in so-called - "transition mode". + "transition mode", while version 2.0 still maintains the legacy + :class:`_orm.Query` object to allow legacy code to remain largely + 2.0 compatible. .. seealso:: diff --git a/doc/build/index.rst b/doc/build/index.rst index 54539c3eb6..37b807723f 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -32,14 +32,14 @@ SQLAlchemy Documentation .. container:: - The SQLAlchemy 2.0 series represents a major rework of the classic 1.x - SQLAlchemy APIs that have evolved over more than 15 years. The new tutorial - is recommended for all new users as well as veterans of older SQLAlchemy - versions alike. + New users of SQLAlchemy, as well as veterans of older SQLAlchemy + release series, should start with the + :doc:`/tutorial/index`, which covers everything an Alchemist needs + to know when using the ORM or just Core. * **For a quick glance:** :doc:`/orm/quickstart` - a glimpse at what working with the ORM looks like - * **For all users:** :doc:`/tutorial/index` - SQLAlchemy 2.0's main tutorial, for complete learning + * **For all users:** :doc:`/tutorial/index` - In depth tutorial for Core and ORM .. container:: left_right_container @@ -52,6 +52,9 @@ SQLAlchemy Documentation .. container:: + Users coming from older versions of SQLAlchemy, especially those transitioning + from the 1.x style of working, will want to review this documentation. + * :doc:`Migrating to SQLAlchemy 2.0 ` - Complete background on migrating from 1.3 or 1.4 to 2.0 * :doc:`What's New in SQLAlchemy 2.0? ` - New 2.0 features and behaviors beyond the 1.x migration * :doc:`Changelog catalog ` - Detailed changelogs for all SQLAlchemy Versions @@ -63,28 +66,27 @@ SQLAlchemy Documentation .. rst-class:: h2 - Reference Documentation + Reference and How To .. container:: orm - **SQLAlchemy ORM** + **SQLAlchemy ORM** - Detailed guides and API reference for using the ORM - * **ORM Configuration:** - :doc:`Mapped Class Configuration ` | + * **Mapping Classes:** + :doc:`Mapping Python Classes ` | :doc:`Relationship Configuration ` - * **ORM Usage:** - :doc:`Session Usage and Guidelines ` | - :doc:`Querying Guide ` | - :doc:`AsyncIO Support ` + * **Using the ORM:** + :doc:`Using the ORM Session ` | + :doc:`ORM Querying Guide ` | + :doc:`Using AsyncIO ` * **Configuration Extensions:** - :doc:`Mypy integration ` | :doc:`Association Proxy ` | :doc:`Hybrid Attributes ` | - :doc:`Automap ` | :doc:`Mutable Scalars ` | + :doc:`Automap ` | :doc:`All extensions ` * **Extending the ORM:** @@ -95,7 +97,7 @@ SQLAlchemy Documentation .. container:: core - **SQLAlchemy Core** + **SQLAlchemy Core** - Detailed guides and API reference for working with Core * **Engines, Connections, Pools:** :doc:`Engine Configuration ` | @@ -111,13 +113,20 @@ SQLAlchemy Documentation :ref:`Constraints and Indexes ` | :ref:`Using Data Definition Language (DDL) ` - * **SQL Reference:** - :doc:`SQL Expression API docs ` + * **SQL Statements:** + :doc:`SQL Expression Elements ` | + :doc:`Operator Reference ` | + :doc:`SELECT and related constructs ` | + :doc:`INSERT, UPDATE, DELETE ` | + :doc:`SQL Functions ` | + :doc:`Table of Contents ` + + * **Datatypes:** :ref:`Overview ` | :ref:`Building Custom Types ` | - :ref:`API ` + :ref:`Type API Reference ` * **Core Basics:** :doc:`Overview ` | diff --git a/doc/build/intro.rst b/doc/build/intro.rst index d42196a2db..fbc2b37041 100644 --- a/doc/build/intro.rst +++ b/doc/build/intro.rst @@ -58,17 +58,15 @@ The documentation is separated into four sections: * :ref:`unified_tutorial` - this all-new tutorial for the 1.4/2.0 series of SQLAlchemy introduces the entire library holistically, starting from a description of Core and working more and more towards ORM-specific concepts. - New users, as well as users coming from :term:`1.x style`, who wish to work - in :term:`2.0 style` should start here. + New users, as well as users coming from the 1.x series of + SQLAlchemy, should start here. * :ref:`orm_toplevel` - In this section, reference documentation for the ORM is - presented; this section also includes the now-legacy - :ref:`ormtutorial_toplevel`. + presented. * :ref:`core_toplevel` - Here, reference documentation for - everything else within Core is presented; section also includes the legacy - :ref:`sqlexpression_toplevel`. SQLAlchemy engine, connection, and pooling - services are also described here. + everything else within Core is presented. SQLAlchemy engine, connection, and + pooling services are also described here. * :ref:`dialect_toplevel` - Provides reference documentation for all :term:`dialect` implementations, including :term:`DBAPI` specifics. @@ -126,11 +124,6 @@ approaches. Install via pip --------------- -.. warning:: This section **does not apply until SQLAlchemy 2.0 is actually - released**, which as of January 26, 2022 the library is **not released yet**. - In the interim, these instructions **will not function** and will install - the latest 1.4 release. - When ``pip`` is available, the distribution can be downloaded from PyPI and installed in one step: diff --git a/doc/build/orm/index.rst b/doc/build/orm/index.rst index 2ede74c3ef..c3fa9929b3 100644 --- a/doc/build/orm/index.rst +++ b/doc/build/orm/index.rst @@ -20,7 +20,3 @@ tutorial. extensions/index examples -.. toctree:: - :hidden: - - tutorial diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index 8388320939..ab0402721d 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -6,8 +6,8 @@ Relationship Configuration ========================== This section describes the :func:`relationship` function and in depth discussion -of its usage. For an introduction to relationships, start with the -:ref:`ormtutorial_toplevel` and head into :ref:`tutorial_orm_related_objects`. +of its usage. For an introduction to relationships, start with +:ref:`tutorial_orm_related_objects` in the :ref:`unified_tutorial`. .. toctree:: :maxdepth: 3 diff --git a/doc/build/orm/session_events.rst b/doc/build/orm/session_events.rst index 980e301d13..5c2b22fc17 100644 --- a/doc/build/orm/session_events.rst +++ b/doc/build/orm/session_events.rst @@ -383,8 +383,6 @@ events include: The reason the :class:`_engine.Connection` is passed is that it is encouraged that **simple SQL operations take place here**, directly on the :class:`_engine.Connection`, such as incrementing counters or inserting extra rows within log tables. -When dealing with the :class:`_engine.Connection`, it is expected that Core-level -SQL operations will be used; e.g. those described in :ref:`sqlexpression_toplevel`. There are also many per-object operations that don't need to be handled within a flush event at all. The most common alternative is to simply diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 0ee0216e96..a32bf1e68f 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -1,4 +1,4 @@ -.. _ormtutorial_toplevel: +:orphan: ========================== Object Relational Tutorial diff --git a/doc/build/tutorial/index.rst b/doc/build/tutorial/index.rst index cc5cb660c4..213162d3f8 100644 --- a/doc/build/tutorial/index.rst +++ b/doc/build/tutorial/index.rst @@ -1,4 +1,4 @@ -.. |tutorial_title| replace:: SQLAlchemy 2.0 Tutorial +.. |tutorial_title| replace:: SQLAlchemy Unified Tutorial .. |next| replace:: :doc:`engine` .. footer_topic:: |tutorial_title| @@ -9,14 +9,13 @@ .. rst-class:: orm_core -======================== -SQLAlchemy 2.0 Tutorial -======================== +============================ +SQLAlchemy Unified Tutorial +============================ .. admonition:: About this document - The SQLAlchemy Tutorial for version 2.0, first published as a preview - within the 1.4 documentation, is integrated between the Core and ORM + The SQLAlchemy Unified Tutorial is integrated between the Core and ORM components of SQLAlchemy and serves as a unified introduction to SQLAlchemy as a whole. For users of SQLAlchemy within the 1.x series, in the :term:`2.0 style` of working, the ORM uses Core-style querying with the @@ -26,8 +25,8 @@ SQLAlchemy 2.0 Tutorial topic is! Users who are already familiar with SQLAlchemy, and especially those - looking to migrate existing applications to work under SQLAlchemy 2.0 - within the 1.4 transitional phase should check out the + looking to migrate existing applications to work under the SQLAlchemy 2.0 + series within the 1.4 transitional phase should check out the :ref:`migration_20_toplevel` document as well. For the newcomer, this document has a **lot** of detail, however by the diff --git a/lib/sqlalchemy/ext/serializer.py b/lib/sqlalchemy/ext/serializer.py index 276971ecea..8d84a1eb04 100644 --- a/lib/sqlalchemy/ext/serializer.py +++ b/lib/sqlalchemy/ext/serializer.py @@ -9,6 +9,11 @@ """Serializer/Deserializer objects for usage with SQLAlchemy query structures, allowing "contextual" deserialization. +.. legacy:: + + The serializer extension is **legacy** and should not be used for + new development. + Any SQLAlchemy query structure, either based on sqlalchemy.sql.* or sqlalchemy.orm.* can be used. The mappers, Tables, Columns, Session etc. which are referenced by the structure are not persisted in serialized