From 6c180ab7434371bc0206e6fcd41df94061b82c80 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 2 Oct 2022 21:22:11 -0400 Subject: [PATCH] the future is here the autodoc for the "future" Engine / Connection were removed, so all these links weren't working. Replace all _future for these with _engine. There was just one _future pointing to select, changed that separately. Change-Id: Ib28270d8da8616b533953204e22eabee9388d620 --- doc/build/changelog/changelog_14.rst | 12 ++-- doc/build/changelog/migration_20.rst | 42 ++++++------ doc/build/orm/session_transaction.rst | 16 ++--- doc/build/tutorial/data_insert.rst | 6 +- doc/build/tutorial/data_select.rst | 2 +- doc/build/tutorial/dbapi_transactions.rst | 66 +++++++++---------- doc/build/tutorial/engine.rst | 10 +-- doc/build/tutorial/metadata.rst | 4 +- lib/sqlalchemy/engine/base.py | 8 +-- lib/sqlalchemy/ext/asyncio/engine.py | 20 +++--- lib/sqlalchemy/ext/asyncio/scoping.py | 37 +++++++++-- lib/sqlalchemy/orm/session.py | 2 +- .../sql/_selectable_constructors.py | 2 +- lib/sqlalchemy/sql/selectable.py | 2 +- 14 files changed, 127 insertions(+), 102 deletions(-) diff --git a/doc/build/changelog/changelog_14.rst b/doc/build/changelog/changelog_14.rst index 085b60262b..2af7394188 100644 --- a/doc/build/changelog/changelog_14.rst +++ b/doc/build/changelog/changelog_14.rst @@ -1731,8 +1731,8 @@ This document details individual issue-level changes made throughout :tags: bug, engine :tickets: 7291 - Fixed issue in future :class:`_future.Connection` object where the - :meth:`_future.Connection.execute` method would not accept a non-dict + Fixed issue in future :class:`_engine.Connection` object where the + :meth:`_engine.Connection.execute` method would not accept a non-dict mapping object, such as SQLAlchemy's own :class:`.RowMapping` or other ``abc.collections.Mapping`` object as a parameter dictionary. @@ -1902,8 +1902,8 @@ This document details individual issue-level changes made throughout :tickets: 7272 :versions: 2.0.0b1 - Fixed issue in future :class:`_future.Engine` where calling upon - :meth:`_future.Engine.begin` and entering the context manager would not + Fixed issue in future :class:`_engine.Engine` where calling upon + :meth:`_engine.Engine.begin` and entering the context manager would not close the connection if the actual BEGIN operation failed for some reason, such as an event handler raising an exception; this use case failed to be tested for the future version of the engine. Note that the "future" context @@ -3772,11 +3772,11 @@ This document details individual issue-level changes made throughout autobegin a transaction but not commit it, which is a behavioral change. When using a :term:`2.0 style` connection object, the behavior is unchanged - from previous 1.4 versions; calling :meth:`_future.Connection.begin_nested` + from previous 1.4 versions; calling :meth:`_engine.Connection.begin_nested` will "autobegin" the outer transaction if not already present, and then as instructed emit a SAVEPOINT, returning the :class:`.NestedTransaction` object. The outer transaction is committed by calling upon - :meth:`_future.Connection.commit`, as is "commit-as-you-go" style usage. + :meth:`_engine.Connection.commit`, as is "commit-as-you-go" style usage. In non-"future" mode, while the old behavior is restored, it also emits a 2.0 deprecation warning as this is a legacy behavior. diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 6f345003c8..210fce9af6 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -359,12 +359,12 @@ transaction-level API in version 2.0. In 1.4, this new API is available by passing the flag ``future=True`` to the :func:`_sa.create_engine` function. -When the :paramref:`_sa.create_engine.future` flag is used, the :class:`_future.Engine` -and :class:`_future.Connection` objects support the 2.0 API fully and not at all -any legacy features, including the new argument format for :meth:`_future.Connection.execute`, +When the :paramref:`_sa.create_engine.future` flag is used, the :class:`_engine.Engine` +and :class:`_engine.Connection` objects support the 2.0 API fully and not at all +any legacy features, including the new argument format for :meth:`_engine.Connection.execute`, the removal of "implicit autocommit", string statements require the -:func:`_sql.text` construct unless the :meth:`_future.Connection.exec_driver_sql` -method is used, and connectionless execution from the :class:`_future.Engine` +:func:`_sql.text` construct unless the :meth:`_engine.Connection.exec_driver_sql` +method is used, and connectionless execution from the :class:`_engine.Engine` is removed. If all :class:`_exc.RemovedIn20Warning` warnings have been resolved regarding @@ -372,11 +372,11 @@ use of the :class:`_engine.Engine` and :class:`_engine.Connection`, then the :paramref:`_sa.create_engine.future` flag may be enabled and there should be no errors raised. -The new engine is described at :class:`_future.Engine` which delivers a new -:class:`_future.Connection` object. In addition to the above changes, the, -:class:`_future.Connection` object features -:meth:`_future.Connection.commit` and -:meth:`_future.Connection.rollback` methods, to support the new +The new engine is described at :class:`_engine.Engine` which delivers a new +:class:`_engine.Connection` object. In addition to the above changes, the, +:class:`_engine.Connection` object features +:meth:`_engine.Connection.commit` and +:meth:`_engine.Connection.rollback` methods, to support the new "commit-as-you-go" mode of operation:: @@ -506,9 +506,9 @@ or the :meth:`_engine.Engine.begin` context manager:: When using :term:`2.0 style` with the :paramref:`_sa.create_engine.future` flag, "commit as you go" style may also be used, as the -:class:`_future.Connection` features **autobegin** behavior, which takes place +:class:`_engine.Connection` features **autobegin** behavior, which takes place when a statement is first invoked in the absence of an explicit call to -:meth:`_future.Connection.begin`:: +:meth:`_engine.Connection.begin`:: with engine.connect() as conn: conn.execute(some_table.insert().values(foo="bar")) @@ -554,10 +554,10 @@ of Core use cases, it's the pattern that is already recommended:: For "commit as you go, or rollback instead" usage, which resembles how the :class:`_orm.Session` is normally used today, the "future" version of -:class:`_future.Connection`, which is the one that is returned from an -:class:`_future.Engine` that was created using the +:class:`_engine.Connection`, which is the one that is returned from an +:class:`_engine.Engine` that was created using the :paramref:`_sa.create_engine.future` flag, includes new -:meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback` +:meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback` methods, which act upon a transaction that is now begun automatically when a statement is first invoked:: @@ -578,8 +578,8 @@ Above, the ``engine.connect()`` method will return a :class:`_engine.Connection` features **autobegin**, meaning the ``begin()`` event is emitted when the execute method is first used (note however that there is no actual "BEGIN" in the Python DBAPI). "autobegin" is a new pattern in SQLAlchemy 1.4 that -is featured both by :class:`_future.Connection` as well as the ORM -:class:`_orm.Session` object; autobegin allows that the :meth:`_future.Connection.begin` +is featured both by :class:`_engine.Connection` as well as the ORM +:class:`_orm.Session` object; autobegin allows that the :meth:`_engine.Connection.begin` method may be called explicitly when the object is first acquired, for schemes that wish to demarcate the beginning of the transaction, but if the method is not called, then it occurs implicitly when work is first done on the object. @@ -599,7 +599,7 @@ implementations, and is supported by SQLAlchemy via the discussed at :ref:`dbapi_autocommit`. True autocommit is treated as an "isolation level" so that the structure of application code does not change when autocommit is used; the :meth:`_engine.Connection.begin` context manager as well as -methods like :meth:`_future.Connection.commit` may still be used, they are +methods like :meth:`_engine.Connection.commit` may still be used, they are simply no-ops at the database driver level when DBAPI-level autocommit is turned on. @@ -803,7 +803,7 @@ execute() method more strict, execution options are more prominent The argument patterns that may be used with the :meth:`_engine.Connection` execute method in SQLAlchemy 2.0 are highly simplified, removing many previously available argument patterns. The new API in the 1.4 series is described at -:meth:`_future.Connection`. The examples below illustrate the patterns that +:meth:`_engine.Connection`. The examples below illustrate the patterns that require modification:: @@ -826,7 +826,7 @@ require modification:: **Migration to 2.0** -The new :meth:`_future.Connection.execute` method now accepts a subset of the +The new :meth:`_engine.Connection.execute` method now accepts a subset of the argument styles that are accepted by the 1.x :meth:`_engine.Connection.execute` method, so the following code is cross-compatible between 1.x and 2.0:: @@ -850,7 +850,7 @@ method, so the following code is cross-compatible between 1.x and 2.0:: The use of ``*args`` and ``**kwargs`` has been removed both to remove the complexity of guessing what kind of arguments were passed to the method, as well as to make room for other options, namely the -:paramref:`_future.Connection.execute.execution_options` dictionary that is now +:paramref:`_engine.Connection.execute.execution_options` dictionary that is now available to provide options on a per statement basis. The method is also modified so that its use pattern matches that of the :meth:`_orm.Session.execute` method, which is a much more prominent API in 2.0 diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst index e8dd484599..6bb8bfb5c8 100644 --- a/doc/build/orm/session_transaction.rst +++ b/doc/build/orm/session_transaction.rst @@ -229,8 +229,8 @@ assume 2.0-style semantics. When using future mode, there should be equivalent semantics between the two packages, at the level of the :class:`_orm.sessionmaker` vs. -the :class:`_future.Engine`, as well as the :class:`_orm.Session` vs. -the :class:`_future.Connection`. The following sections detail +the :class:`_engine.Engine`, as well as the :class:`_orm.Session` vs. +the :class:`_engine.Connection`. The following sections detail these scenarios based on the following scheme:: @@ -247,8 +247,8 @@ these scenarios based on the following scheme:: Commit as you go ~~~~~~~~~~~~~~~~ -Both :class:`_orm.Session` and :class:`_future.Connection` feature -:meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback` +Both :class:`_orm.Session` and :class:`_engine.Connection` feature +:meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback` methods. Using SQLAlchemy 2.0-style operation, these methods affect the **outermost** transaction in all cases. @@ -285,10 +285,10 @@ Session:: Begin Once ~~~~~~~~~~ -Both :class:`_orm.sessionmaker` and :class:`_future.Engine` feature a -:meth:`_future.Engine.begin` method that will both procure a new object +Both :class:`_orm.sessionmaker` and :class:`_engine.Engine` feature a +:meth:`_engine.Engine.begin` method that will both procure a new object with which to execute SQL statements (the :class:`_orm.Session` and -:class:`_future.Connection`, respectively) and then return a context manager +:class:`_engine.Connection`, respectively) and then return a context manager that will maintain a begin/commit/rollback context for that object. Engine:: @@ -326,7 +326,7 @@ Nested Transaction When using a SAVEPOINT via the :meth:`_orm.Session.begin_nested` or :meth:`_engine.Connection.begin_nested` methods, the transaction object returned must be used to commit or rollback the SAVEPOINT. Calling -the :meth:`_orm.Session.commit` or :meth:`_future.Connection.commit` methods +the :meth:`_orm.Session.commit` or :meth:`_engine.Connection.commit` methods will always commit the **outermost** transaction; this is a SQLAlchemy 2.0 specific behavior that is reversed from the 1.x series. diff --git a/doc/build/tutorial/data_insert.rst b/doc/build/tutorial/data_insert.rst index c1df86120e..36c3414c61 100644 --- a/doc/build/tutorial/data_insert.rst +++ b/doc/build/tutorial/data_insert.rst @@ -112,7 +112,7 @@ in fact has some variants that allow for special forms such as multiple rows in one statement and insertion of SQL expressions. However the usual way that :class:`_sql.Insert` is used is such that the VALUES clause is generated automatically from the parameters passed to the -:meth:`_future.Connection.execute` method; below we INSERT two more rows to +:meth:`_engine.Connection.execute` method; below we INSERT two more rows to illustrate this: .. sourcecode:: pycon+sql @@ -134,9 +134,9 @@ illustrate this: The execution above features "executemany" form first illustrated at :ref:`tutorial_multiple_parameters`, however unlike when using the :func:`_sql.text` construct, we didn't have to spell out any SQL. -By passing a dictionary or list of dictionaries to the :meth:`_future.Connection.execute` +By passing a dictionary or list of dictionaries to the :meth:`_engine.Connection.execute` method in conjunction with the :class:`_sql.Insert` construct, the -:class:`_future.Connection` ensures that the column names which are passed +:class:`_engine.Connection` ensures that the column names which are passed will be expressed in the VALUES clause of the :class:`_sql.Insert` construct automatically. diff --git a/doc/build/tutorial/data_select.rst b/doc/build/tutorial/data_select.rst index e187ab16c6..64b9cef8ae 100644 --- a/doc/build/tutorial/data_select.rst +++ b/doc/build/tutorial/data_select.rst @@ -14,7 +14,7 @@ Selecting Rows with Core or ORM For both Core and ORM, the :func:`_sql.select` function generates a :class:`_sql.Select` construct which is used for all SELECT queries. -Passed to methods like :meth:`_future.Connection.execute` in Core and +Passed to methods like :meth:`_engine.Connection.execute` in Core and :meth:`_orm.Session.execute` in ORM, a SELECT statement is emitted in the current transaction and the result rows available via the returned :class:`_engine.Result` object. diff --git a/doc/build/tutorial/dbapi_transactions.rst b/doc/build/tutorial/dbapi_transactions.rst index 89b8f423d2..780b3166b7 100644 --- a/doc/build/tutorial/dbapi_transactions.rst +++ b/doc/build/tutorial/dbapi_transactions.rst @@ -11,9 +11,9 @@ Working with Transactions and the DBAPI -With the :class:`_future.Engine` object ready to go, we may now proceed -to dive into the basic operation of an :class:`_future.Engine` and -its primary interactive endpoints, the :class:`_future.Connection` and +With the :class:`_engine.Engine` object ready to go, we may now proceed +to dive into the basic operation of an :class:`_engine.Engine` and +its primary interactive endpoints, the :class:`_engine.Connection` and :class:`_engine.Result`. We will additionally introduce the ORM's :term:`facade` for these objects, known as the :class:`_orm.Session`. @@ -21,13 +21,13 @@ its primary interactive endpoints, the :class:`_future.Connection` and **Note to ORM readers** - When using the ORM, the :class:`_future.Engine` is managed by another + When using the ORM, the :class:`_engine.Engine` is managed by another object called the :class:`_orm.Session`. The :class:`_orm.Session` in modern SQLAlchemy emphasizes a transactional and SQL execution pattern that - is largely identical to that of the :class:`_future.Connection` discussed + is largely identical to that of the :class:`_engine.Connection` discussed below, so while this subsection is Core-centric, all of the concepts here are essentially relevant to ORM use as well and is recommended for all ORM - learners. The execution pattern used by the :class:`_future.Connection` + learners. The execution pattern used by the :class:`_engine.Connection` will be contrasted with that of the :class:`_orm.Session` at the end of this section. @@ -45,11 +45,11 @@ tasks, even though it always remains fully available. Getting a Connection --------------------- -The sole purpose of the :class:`_future.Engine` object from a user-facing +The sole purpose of the :class:`_engine.Engine` object from a user-facing perspective is to provide a unit of -connectivity to the database called the :class:`_future.Connection`. When -working with the Core directly, the :class:`_future.Connection` object -is how all interaction with the database is done. As the :class:`_future.Connection` +connectivity to the database called the :class:`_engine.Connection`. When +working with the Core directly, the :class:`_engine.Connection` object +is how all interaction with the database is done. As the :class:`_engine.Connection` represents an open resource against the database, we want to always limit the scope of our use of this object to a specific context, and the best way to do that is by using Python context manager form, also known as @@ -76,7 +76,7 @@ and also framed the operation inside of a transaction. The default behavior of the Python DBAPI includes that a transaction is always in progress; when the scope of the connection is :term:`released`, a ROLLBACK is emitted to end the transaction. The transaction is **not committed automatically**; when we want -to commit data we normally need to call :meth:`_future.Connection.commit` +to commit data we normally need to call :meth:`_engine.Connection.commit` as we'll see in the next section. .. tip:: "autocommit" mode is available for special cases. The section @@ -97,8 +97,8 @@ Committing Changes We just learned that the DBAPI connection is non-autocommitting. What if we want to commit some data? We can alter our above example to create a table and insert some data, and the transaction is then committed using -the :meth:`_future.Connection.commit` method, invoked **inside** the block -where we acquired the :class:`_future.Connection` object: +the :meth:`_engine.Connection.commit` method, invoked **inside** the block +where we acquired the :class:`_engine.Connection` object: .. sourcecode:: pycon+sql @@ -124,17 +124,17 @@ Above, we emitted two SQL statements that are generally transactional, a (the parameterization syntax above is discussed a few sections below in :ref:`tutorial_multiple_parameters`). As we want the work we've done to be committed within our block, we invoke the -:meth:`_future.Connection.commit` method which commits the transaction. After +:meth:`_engine.Connection.commit` method which commits the transaction. After we call this method inside the block, we can continue to run more SQL -statements and if we choose we may call :meth:`_future.Connection.commit` +statements and if we choose we may call :meth:`_engine.Connection.commit` again for subsequent statements. SQLAlchemy refers to this style as **commit as you go**. There is also another style of committing data, which is that we can declare our "connect" block to be a transaction block up front. For this mode of -operation, we use the :meth:`_future.Engine.begin` method to acquire the -connection, rather than the :meth:`_future.Engine.connect` method. This method -will both manage the scope of the :class:`_future.Connection` and also +operation, we use the :meth:`_engine.Engine.begin` method to acquire the +connection, rather than the :meth:`_engine.Engine.connect` method. This method +will both manage the scope of the :class:`_engine.Connection` and also enclose everything inside of a transaction with COMMIT at the end, assuming a successful block, or ROLLBACK in case of exception raise. This style may be referred towards as **begin once**: @@ -185,7 +185,7 @@ Basics of Statement Execution ----------------------------- We have seen a few examples that run SQL statements against a database, making -use of a method called :meth:`_future.Connection.execute`, in conjunction with +use of a method called :meth:`_engine.Connection.execute`, in conjunction with an object called :func:`_sql.text`, and returning an object called :class:`_engine.Result`. In this section we'll illustrate more closely the mechanics and interactions of these components. @@ -194,7 +194,7 @@ mechanics and interactions of these components. Most of the content in this section applies equally well to modern ORM use when using the :meth:`_orm.Session.execute` method, which works - very similarly to that of :meth:`_future.Connection.execute`, including that + very similarly to that of :meth:`_engine.Connection.execute`, including that ORM result rows are delivered using the same :class:`_engine.Result` interface used by Core. @@ -300,7 +300,7 @@ Sending Parameters SQL statements are usually accompanied by data that is to be passed with the statement itself, as we saw in the INSERT example previously. The -:meth:`_future.Connection.execute` method therefore also accepts parameters, +:meth:`_engine.Connection.execute` method therefore also accepts parameters, which are referred towards as :term:`bound parameters`. A rudimentary example might be if we wanted to limit our SELECT statement only to rows that meet a certain criteria, such as rows where the "y" value were greater than a certain @@ -311,7 +311,7 @@ that the driver can properly sanitize the value, we add a WHERE criteria to our statement that names a new parameter called "y"; the :func:`_sql.text` construct accepts these using a colon format "``:y``". The actual value for "``:y``" is then passed as the second argument to -:meth:`_future.Connection.execute` in the form of a dictionary: +:meth:`_engine.Connection.execute` in the form of a dictionary: .. sourcecode:: pycon+sql @@ -358,7 +358,7 @@ statement where it appeared that we were able to INSERT multiple rows into the database at once. For statements that **operate upon data, but do not return result sets**, namely :term:`DML` statements such as "INSERT" which don't include a phrase like "RETURNING", we can send **multi params** to the -:meth:`_future.Connection.execute` method by passing a list of dictionaries +:meth:`_engine.Connection.execute` method by passing a list of dictionaries instead of a single dictionary, thus allowing the single SQL statement to be invoked against each parameter set individually: @@ -376,7 +376,7 @@ be invoked against each parameter set individually: COMMIT -Behind the scenes, the :class:`_future.Connection` objects uses a DBAPI feature +Behind the scenes, the :class:`_engine.Connection` objects uses a DBAPI feature known as `cursor.executemany() `_. This method performs the equivalent operation of invoking the given SQL statement against each parameter @@ -410,19 +410,19 @@ terms of Core and ORM use together. The fundamental transactional / database interactive object when using the ORM is called the :class:`_orm.Session`. In modern SQLAlchemy, this object -is used in a manner very similar to that of the :class:`_future.Connection`, +is used in a manner very similar to that of the :class:`_engine.Connection`, and in fact as the :class:`_orm.Session` is used, it refers to a -:class:`_future.Connection` internally which it uses to emit SQL. +:class:`_engine.Connection` internally which it uses to emit SQL. When the :class:`_orm.Session` is used with non-ORM constructs, it passes through the SQL statements we give it and does not generally do things -much differently from how the :class:`_future.Connection` does directly, so +much differently from how the :class:`_engine.Connection` does directly, so we can illustrate it here in terms of the simple textual SQL operations we've already learned. The :class:`_orm.Session` has a few different creational patterns, but here we will illustrate the most basic one that tracks exactly with how -the :class:`_future.Connection` is used which is to construct it within +the :class:`_engine.Connection` is used which is to construct it within a context manager: .. sourcecode:: pycon+sql @@ -447,9 +447,9 @@ The example above can be compared to the example in the preceding section in :ref:`tutorial_sending_parameters` - we directly replace the call to ``with engine.connect() as conn`` with ``with Session(engine) as session``, and then make use of the :meth:`_orm.Session.execute` method just like we -do with the :meth:`_future.Connection.execute` method. +do with the :meth:`_engine.Connection.execute` method. -Also, like the :class:`_future.Connection`, the :class:`_orm.Session` features +Also, like the :class:`_engine.Connection`, the :class:`_orm.Session` features "commit as you go" behavior using the :meth:`_orm.Session.commit` method, illustrated below using a textual UPDATE statement to alter some of our data: @@ -472,13 +472,13 @@ style of execution introduced at :ref:`tutorial_multiple_parameters`, ending the block with a "commit as you go" commit. .. tip:: The :class:`_orm.Session` doesn't actually hold onto the - :class:`_future.Connection` object after it ends the transaction. It - gets a new :class:`_future.Connection` from the :class:`_future.Engine` + :class:`_engine.Connection` object after it ends the transaction. It + gets a new :class:`_engine.Connection` from the :class:`_engine.Engine` when executing SQL against the database is next needed. The :class:`_orm.Session` obviously has a lot more tricks up its sleeve than that, however understanding that it has a :meth:`_orm.Session.execute` -method that's used the same way as :meth:`_future.Connection.execute` will +method that's used the same way as :meth:`_engine.Connection.execute` will get us started with the examples that follow later. .. seealso:: diff --git a/doc/build/tutorial/engine.rst b/doc/build/tutorial/engine.rst index fc8973c465..e42d67a022 100644 --- a/doc/build/tutorial/engine.rst +++ b/doc/build/tutorial/engine.rst @@ -10,7 +10,7 @@ Establishing Connectivity - the Engine The start of any SQLAlchemy application is an object called the -:class:`_future.Engine`. This object acts as a central source of connections +:class:`_engine.Engine`. This object acts as a central source of connections to a particular database, providing both a factory as well as a holding space called a :ref:`connection pool ` for these database connections. The engine is typically a global object created just @@ -19,7 +19,7 @@ which will describe how it should connect to the database host or backend. For this tutorial we will use an in-memory-only SQLite database. This is an easy way to test things without needing to have an actual pre-existing database -set up. The :class:`_future.Engine` is created by using :func:`_sa.create_engine`, specifying +set up. The :class:`_engine.Engine` is created by using :func:`_sa.create_engine`, specifying the :paramref:`_sa.create_engine.future` flag set to ``True`` so that we make full use of :term:`2.0 style` usage: @@ -30,7 +30,7 @@ of :term:`2.0 style` usage: The main argument to :class:`_sa.create_engine` is a string URL, above passed as the string ``"sqlite+pysqlite:///:memory:"``. -This string indicates to the :class:`_future.Engine` three important +This string indicates to the :class:`_engine.Engine` three important facts: 1. What kind of database are we communicating with? This is the ``sqlite`` @@ -52,13 +52,13 @@ facts: .. sidebar:: Lazy Connecting - The :class:`_future.Engine`, when first returned by :func:`_sa.create_engine`, + The :class:`_engine.Engine`, when first returned by :func:`_sa.create_engine`, has not actually tried to connect to the database yet; that happens only the first time it is asked to perform a task against the database. This is a software design pattern known as :term:`lazy initialization`. We have also specified a parameter :paramref:`_sa.create_engine.echo`, which -will instruct the :class:`_future.Engine` to log all of the SQL it emits to a +will instruct the :class:`_engine.Engine` to log all of the SQL it emits to a Python logger that will write to standard out. This flag is a shorthand way of setting up :ref:`Python logging more formally ` and is useful for diff --git a/doc/build/tutorial/metadata.rst b/doc/build/tutorial/metadata.rst index 7816bae677..d8cc30d9b2 100644 --- a/doc/build/tutorial/metadata.rst +++ b/doc/build/tutorial/metadata.rst @@ -189,7 +189,7 @@ TABLE statements, or :term:`DDL`, to our SQLite database so that we can insert and query data from them. We have already all the tools needed to do so, by invoking the :meth:`_schema.MetaData.create_all` method on our :class:`_schema.MetaData`, -sending it the :class:`_future.Engine` that refers to the target database: +sending it the :class:`_engine.Engine` that refers to the target database: .. sourcecode:: pycon+sql @@ -550,7 +550,7 @@ how this is performed, however the most basic is to construct a :class:`_schema.Table` object, given the name of the table and a :class:`_schema.MetaData` collection to which it will belong, then instead of indicating individual :class:`_schema.Column` and -:class:`_schema.Constraint` objects, pass it the target :class:`_future.Engine` +:class:`_schema.Constraint` objects, pass it the target :class:`_engine.Engine` using the :paramref:`_schema.Table.autoload_with` parameter: .. sourcecode:: pycon+sql diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 1b07acab55..1ec3072975 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -2603,13 +2603,13 @@ class RootTransaction(Transaction): accessible via the :attr:`_engine.Connection.get_transaction` method of :class:`_engine.Connection`. - In :term:`2.0 style` use, the :class:`_future.Connection` also employs + In :term:`2.0 style` use, the :class:`_engine.Connection` also employs "autobegin" behavior that will create a new :class:`_engine.RootTransaction` whenever a connection in a non-transactional state is used to emit commands on the DBAPI connection. The scope of the :class:`_engine.RootTransaction` in 2.0 style - use can be controlled using the :meth:`_future.Connection.commit` and - :meth:`_future.Connection.rollback` methods. + use can be controlled using the :meth:`_engine.Connection.commit` and + :meth:`_engine.Connection.rollback` methods. """ @@ -2865,7 +2865,7 @@ class Engine( This is the **SQLAlchemy 1.x version** of :class:`_engine.Engine`. For the :term:`2.0 style` version, which includes some API differences, - see :class:`_future.Engine`. + see :class:`_engine.Engine`. An :class:`_engine.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. diff --git a/lib/sqlalchemy/ext/asyncio/engine.py b/lib/sqlalchemy/ext/asyncio/engine.py index 4d0c872b30..19ef4d3a1d 100644 --- a/lib/sqlalchemy/ext/asyncio/engine.py +++ b/lib/sqlalchemy/ext/asyncio/engine.py @@ -352,7 +352,7 @@ class AsyncConnection( This returns this :class:`_asyncio.AsyncConnection` object with the new options added. - See :meth:`_future.Connection.execution_options` for full details + See :meth:`_engine.Connection.execution_options` for full details on this method. """ @@ -369,9 +369,9 @@ class AsyncConnection( If no transaction was started, the method has no effect, assuming the connection is in a non-invalidated state. - A transaction is begun on a :class:`_future.Connection` automatically + A transaction is begun on a :class:`_engine.Connection` automatically whenever a statement is first executed, or when the - :meth:`_future.Connection.begin` method is called. + :meth:`_engine.Connection.begin` method is called. """ await greenlet_spawn(self._proxied.commit) @@ -384,9 +384,9 @@ class AsyncConnection( transaction was started and the connection is in an invalidated state, the transaction is cleared using this method. - A transaction is begun on a :class:`_future.Connection` automatically + A transaction is begun on a :class:`_engine.Connection` automatically whenever a statement is first executed, or when the - :meth:`_future.Connection.begin` method is called. + :meth:`_engine.Connection.begin` method is called. """ @@ -519,7 +519,7 @@ class AsyncConnection( :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted - by :meth:`_future.Connection.execution_options`. + by :meth:`_engine.Connection.execution_options`. :return: a :class:`_engine.Result` object. @@ -564,7 +564,7 @@ class AsyncConnection( This method is shorthand for invoking the :meth:`_engine.Result.scalar` method after invoking the - :meth:`_future.Connection.execute` method. Parameters are equivalent. + :meth:`_engine.Connection.execute` method. Parameters are equivalent. :return: a scalar Python value representing the first column of the first row returned. @@ -606,7 +606,7 @@ class AsyncConnection( This method is shorthand for invoking the :meth:`_engine.Result.scalars` method after invoking the - :meth:`_future.Connection.execute` method. Parameters are equivalent. + :meth:`_engine.Connection.execute` method. Parameters are equivalent. :return: a :class:`_engine.ScalarResult` object. @@ -650,7 +650,7 @@ class AsyncConnection( This method is shorthand for invoking the :meth:`_engine.AsyncResult.scalars` method after invoking the - :meth:`_future.Connection.stream` method. Parameters are equivalent. + :meth:`_engine.Connection.stream` method. Parameters are equivalent. :return: an :class:`_asyncio.AsyncScalarResult` object. @@ -931,7 +931,7 @@ class AsyncEngine(ProxyComparable[Engine], AsyncConnectable): :class:`_asyncio.AsyncConnection` objects with the given execution options. - Proxied from :meth:`_future.Engine.execution_options`. See that + Proxied from :meth:`_engine.Engine.execution_options`. See that method for details. """ diff --git a/lib/sqlalchemy/ext/asyncio/scoping.py b/lib/sqlalchemy/ext/asyncio/scoping.py index 8d31dd07d4..a2fec1c246 100644 --- a/lib/sqlalchemy/ext/asyncio/scoping.py +++ b/lib/sqlalchemy/ext/asyncio/scoping.py @@ -301,7 +301,7 @@ class async_scoped_session(Generic[_AS]): return self._proxied.__iter__() def add(self, instance: object, _warn: bool = True) -> None: - r"""Place an object in the ``Session``. + r"""Place an object into this :class:`_orm.Session`. .. container:: class_bases @@ -313,11 +313,26 @@ class async_scoped_session(Generic[_AS]): Proxied for the :class:`_orm.Session` class on behalf of the :class:`_asyncio.AsyncSession` class. - Its state will be persisted to the database on the next flush - operation. + Objects that are in the :term:`transient` state when passed to the + :meth:`_orm.Session.add` method will move to the + :term:`pending` state, until the next flush, at which point they + will move to the :term:`persistent` state. - Repeated calls to ``add()`` will be ignored. The opposite of ``add()`` - is ``expunge()``. + Objects that are in the :term:`detached` state when passed to the + :meth:`_orm.Session.add` method will move to the :term:`persistent` + state directly. + + If the transaction used by the :class:`_orm.Session` is rolled back, + objects which were transient when they were passed to + :meth:`_orm.Session.add` will be moved back to the + :term:`transient` state, and will no longer be present within this + :class:`_orm.Session`. + + .. seealso:: + + :meth:`_orm.Session.add_all` + + :ref:`session_adding` - at :ref:`session_basics` @@ -326,7 +341,7 @@ class async_scoped_session(Generic[_AS]): return self._proxied.add(instance, _warn=_warn) def add_all(self, instances: Iterable[object]) -> None: - r"""Add the given collection of instances to this ``Session``. + r"""Add the given collection of instances to this :class:`_orm.Session`. .. container:: class_bases @@ -338,6 +353,16 @@ class async_scoped_session(Generic[_AS]): Proxied for the :class:`_orm.Session` class on behalf of the :class:`_asyncio.AsyncSession` class. + See the documentation for :meth:`_orm.Session.add` for a general + behavioral description. + + .. seealso:: + + :meth:`_orm.Session.add` + + :ref:`session_adding` - at :ref:`session_basics` + + """ # noqa: E501 diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index ce7caa3ee9..9577b4d260 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -280,7 +280,7 @@ class ORMExecuteState(util.MemoizedSlots): For an ORM selection as would be retrieved from :class:`_orm.Query`, this is an instance of - :class:`_future.select` that was generated from the ORM query. + :class:`_sql.select` that was generated from the ORM query. """ parameters: Optional[_CoreAnyExecuteParams] diff --git a/lib/sqlalchemy/sql/_selectable_constructors.py b/lib/sqlalchemy/sql/_selectable_constructors.py index b661d6f477..a0dbb5fb59 100644 --- a/lib/sqlalchemy/sql/_selectable_constructors.py +++ b/lib/sqlalchemy/sql/_selectable_constructors.py @@ -456,7 +456,7 @@ def select(*entities: _ColumnsClauseArgument[Any], **__kw: Any) -> Select[Any]: .. versionadded:: 1.4 - The :func:`_sql.select` function now accepts column arguments positionally. The top-level :func:`_sql.select` function will automatically use the 1.x or 2.x style API based on - the incoming arguments; using :func:`_future.select` from the + the incoming arguments; using :func:`_sql.select` from the ``sqlalchemy.future`` module will enforce that only the 2.x style constructor is used. diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 8de93c2b4c..bdc884d7be 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -5068,7 +5068,7 @@ class Select( def filter( self: SelfSelect, *criteria: _ColumnExpressionArgument[bool] ) -> SelfSelect: - """A synonym for the :meth:`_future.Select.where` method.""" + """A synonym for the :meth:`_sql.Select.where` method.""" return self.where(*criteria) -- 2.47.2