Skip to content

Commit 6c180ab

Browse files
zzzeekzzzeek
committed
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
1 parent 7051dc5 commit 6c180ab

14 files changed

Lines changed: 127 additions & 102 deletions

File tree

‎doc/build/changelog/changelog_14.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1731,8 +1731,8 @@ This document details individual issue-level changes made throughout
17311731
:tags: bug, engine
17321732
:tickets: 7291
17331733

1734-
Fixed issue in future :class:`_future.Connection` object where the
1735-
:meth:`_future.Connection.execute` method would not accept a non-dict
1734+
Fixed issue in future :class:`_engine.Connection` object where the
1735+
:meth:`_engine.Connection.execute` method would not accept a non-dict
17361736
mapping object, such as SQLAlchemy's own :class:`.RowMapping` or other
17371737
``abc.collections.Mapping`` object as a parameter dictionary.
17381738

@@ -1902,8 +1902,8 @@ This document details individual issue-level changes made throughout
19021902
:tickets: 7272
19031903
:versions: 2.0.0b1
19041904

1905-
Fixed issue in future :class:`_future.Engine` where calling upon
1906-
:meth:`_future.Engine.begin` and entering the context manager would not
1905+
Fixed issue in future :class:`_engine.Engine` where calling upon
1906+
:meth:`_engine.Engine.begin` and entering the context manager would not
19071907
close the connection if the actual BEGIN operation failed for some reason,
19081908
such as an event handler raising an exception; this use case failed to be
19091909
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
37723772
autobegin a transaction but not commit it, which is a behavioral change.
37733773

37743774
When using a :term:`2.0 style` connection object, the behavior is unchanged
3775-
from previous 1.4 versions; calling :meth:`_future.Connection.begin_nested`
3775+
from previous 1.4 versions; calling :meth:`_engine.Connection.begin_nested`
37763776
will "autobegin" the outer transaction if not already present, and then as
37773777
instructed emit a SAVEPOINT, returning the :class:`.NestedTransaction`
37783778
object. The outer transaction is committed by calling upon
3779-
:meth:`_future.Connection.commit`, as is "commit-as-you-go" style usage.
3779+
:meth:`_engine.Connection.commit`, as is "commit-as-you-go" style usage.
37803780

37813781
In non-"future" mode, while the old behavior is restored, it also
37823782
emits a 2.0 deprecation warning as this is a legacy behavior.

‎doc/build/changelog/migration_20.rst‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -359,24 +359,24 @@ transaction-level API in version 2.0. In 1.4, this new API is available
359359
by passing the flag ``future=True`` to the :func:`_sa.create_engine`
360360
function.
361361

362-
When the :paramref:`_sa.create_engine.future` flag is used, the :class:`_future.Engine`
363-
and :class:`_future.Connection` objects support the 2.0 API fully and not at all
364-
any legacy features, including the new argument format for :meth:`_future.Connection.execute`,
362+
When the :paramref:`_sa.create_engine.future` flag is used, the :class:`_engine.Engine`
363+
and :class:`_engine.Connection` objects support the 2.0 API fully and not at all
364+
any legacy features, including the new argument format for :meth:`_engine.Connection.execute`,
365365
the removal of "implicit autocommit", string statements require the
366-
:func:`_sql.text` construct unless the :meth:`_future.Connection.exec_driver_sql`
367-
method is used, and connectionless execution from the :class:`_future.Engine`
366+
:func:`_sql.text` construct unless the :meth:`_engine.Connection.exec_driver_sql`
367+
method is used, and connectionless execution from the :class:`_engine.Engine`
368368
is removed.
369369

370370
If all :class:`_exc.RemovedIn20Warning` warnings have been resolved regarding
371371
use of the :class:`_engine.Engine` and :class:`_engine.Connection`, then the
372372
:paramref:`_sa.create_engine.future` flag may be enabled and there should be
373373
no errors raised.
374374

375-
The new engine is described at :class:`_future.Engine` which delivers a new
376-
:class:`_future.Connection` object. In addition to the above changes, the,
377-
:class:`_future.Connection` object features
378-
:meth:`_future.Connection.commit` and
379-
:meth:`_future.Connection.rollback` methods, to support the new
375+
The new engine is described at :class:`_engine.Engine` which delivers a new
376+
:class:`_engine.Connection` object. In addition to the above changes, the,
377+
:class:`_engine.Connection` object features
378+
:meth:`_engine.Connection.commit` and
379+
:meth:`_engine.Connection.rollback` methods, to support the new
380380
"commit-as-you-go" mode of operation::
381381

382382

@@ -506,9 +506,9 @@ or the :meth:`_engine.Engine.begin` context manager::
506506

507507
When using :term:`2.0 style` with the :paramref:`_sa.create_engine.future`
508508
flag, "commit as you go" style may also be used, as the
509-
:class:`_future.Connection` features **autobegin** behavior, which takes place
509+
:class:`_engine.Connection` features **autobegin** behavior, which takes place
510510
when a statement is first invoked in the absence of an explicit call to
511-
:meth:`_future.Connection.begin`::
511+
:meth:`_engine.Connection.begin`::
512512

513513
with engine.connect() as conn:
514514
conn.execute(some_table.insert().values(foo="bar"))
@@ -554,10 +554,10 @@ of Core use cases, it's the pattern that is already recommended::
554554

555555
For "commit as you go, or rollback instead" usage, which resembles how the
556556
:class:`_orm.Session` is normally used today, the "future" version of
557-
:class:`_future.Connection`, which is the one that is returned from an
558-
:class:`_future.Engine` that was created using the
557+
:class:`_engine.Connection`, which is the one that is returned from an
558+
:class:`_engine.Engine` that was created using the
559559
:paramref:`_sa.create_engine.future` flag, includes new
560-
:meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback`
560+
:meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback`
561561
methods, which act upon a transaction that is now begun automatically when
562562
a statement is first invoked::
563563

@@ -578,8 +578,8 @@ Above, the ``engine.connect()`` method will return a :class:`_engine.Connection`
578578
features **autobegin**, meaning the ``begin()`` event is emitted when the
579579
execute method is first used (note however that there is no actual "BEGIN" in
580580
the Python DBAPI). "autobegin" is a new pattern in SQLAlchemy 1.4 that
581-
is featured both by :class:`_future.Connection` as well as the ORM
582-
:class:`_orm.Session` object; autobegin allows that the :meth:`_future.Connection.begin`
581+
is featured both by :class:`_engine.Connection` as well as the ORM
582+
:class:`_orm.Session` object; autobegin allows that the :meth:`_engine.Connection.begin`
583583
method may be called explicitly when the object is first acquired, for schemes
584584
that wish to demarcate the beginning of the transaction, but if the method
585585
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
599599
discussed at :ref:`dbapi_autocommit`. True autocommit is treated as an "isolation level"
600600
so that the structure of application code does not change when autocommit is
601601
used; the :meth:`_engine.Connection.begin` context manager as well as
602-
methods like :meth:`_future.Connection.commit` may still be used, they are
602+
methods like :meth:`_engine.Connection.commit` may still be used, they are
603603
simply no-ops at the database driver level when DBAPI-level autocommit
604604
is turned on.
605605

@@ -803,7 +803,7 @@ execute() method more strict, execution options are more prominent
803803
The argument patterns that may be used with the :meth:`_engine.Connection`
804804
execute method in SQLAlchemy 2.0 are highly simplified, removing many previously
805805
available argument patterns. The new API in the 1.4 series is described at
806-
:meth:`_future.Connection`. The examples below illustrate the patterns that
806+
:meth:`_engine.Connection`. The examples below illustrate the patterns that
807807
require modification::
808808

809809

@@ -826,7 +826,7 @@ require modification::
826826

827827
**Migration to 2.0**
828828

829-
The new :meth:`_future.Connection.execute` method now accepts a subset of the
829+
The new :meth:`_engine.Connection.execute` method now accepts a subset of the
830830
argument styles that are accepted by the 1.x :meth:`_engine.Connection.execute`
831831
method, so the following code is cross-compatible between 1.x and 2.0::
832832

@@ -850,7 +850,7 @@ method, so the following code is cross-compatible between 1.x and 2.0::
850850
The use of ``*args`` and ``**kwargs`` has been removed both to remove the
851851
complexity of guessing what kind of arguments were passed to the method, as
852852
well as to make room for other options, namely the
853-
:paramref:`_future.Connection.execute.execution_options` dictionary that is now
853+
:paramref:`_engine.Connection.execute.execution_options` dictionary that is now
854854
available to provide options on a per statement basis. The method is also
855855
modified so that its use pattern matches that of the
856856
:meth:`_orm.Session.execute` method, which is a much more prominent API in 2.0

‎doc/build/orm/session_transaction.rst‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -229,8 +229,8 @@ assume 2.0-style semantics.
229229

230230
When using future mode, there should be equivalent semantics between
231231
the two packages, at the level of the :class:`_orm.sessionmaker` vs.
232-
the :class:`_future.Engine`, as well as the :class:`_orm.Session` vs.
233-
the :class:`_future.Connection`. The following sections detail
232+
the :class:`_engine.Engine`, as well as the :class:`_orm.Session` vs.
233+
the :class:`_engine.Connection`. The following sections detail
234234
these scenarios based on the following scheme::
235235

236236

@@ -247,8 +247,8 @@ these scenarios based on the following scheme::
247247
Commit as you go
248248
~~~~~~~~~~~~~~~~
249249

250-
Both :class:`_orm.Session` and :class:`_future.Connection` feature
251-
:meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback`
250+
Both :class:`_orm.Session` and :class:`_engine.Connection` feature
251+
:meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback`
252252
methods. Using SQLAlchemy 2.0-style operation, these methods affect the
253253
**outermost** transaction in all cases.
254254

@@ -285,10 +285,10 @@ Session::
285285
Begin Once
286286
~~~~~~~~~~
287287

288-
Both :class:`_orm.sessionmaker` and :class:`_future.Engine` feature a
289-
:meth:`_future.Engine.begin` method that will both procure a new object
288+
Both :class:`_orm.sessionmaker` and :class:`_engine.Engine` feature a
289+
:meth:`_engine.Engine.begin` method that will both procure a new object
290290
with which to execute SQL statements (the :class:`_orm.Session` and
291-
:class:`_future.Connection`, respectively) and then return a context manager
291+
:class:`_engine.Connection`, respectively) and then return a context manager
292292
that will maintain a begin/commit/rollback context for that object.
293293

294294
Engine::
@@ -326,7 +326,7 @@ Nested Transaction
326326
When using a SAVEPOINT via the :meth:`_orm.Session.begin_nested` or
327327
:meth:`_engine.Connection.begin_nested` methods, the transaction object
328328
returned must be used to commit or rollback the SAVEPOINT. Calling
329-
the :meth:`_orm.Session.commit` or :meth:`_future.Connection.commit` methods
329+
the :meth:`_orm.Session.commit` or :meth:`_engine.Connection.commit` methods
330330
will always commit the **outermost** transaction; this is a SQLAlchemy 2.0
331331
specific behavior that is reversed from the 1.x series.
332332

‎doc/build/tutorial/data_insert.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ in fact has some variants that allow for special forms such as multiple rows in
112112
one statement and insertion of SQL expressions. However the usual way that
113113
:class:`_sql.Insert` is used is such that the VALUES clause is generated
114114
automatically from the parameters passed to the
115-
:meth:`_future.Connection.execute` method; below we INSERT two more rows to
115+
:meth:`_engine.Connection.execute` method; below we INSERT two more rows to
116116
illustrate this:
117117

118118
.. sourcecode:: pycon+sql
@@ -134,9 +134,9 @@ illustrate this:
134134
The execution above features "executemany" form first illustrated at
135135
:ref:`tutorial_multiple_parameters`, however unlike when using the
136136
:func:`_sql.text` construct, we didn't have to spell out any SQL.
137-
By passing a dictionary or list of dictionaries to the :meth:`_future.Connection.execute`
137+
By passing a dictionary or list of dictionaries to the :meth:`_engine.Connection.execute`
138138
method in conjunction with the :class:`_sql.Insert` construct, the
139-
:class:`_future.Connection` ensures that the column names which are passed
139+
:class:`_engine.Connection` ensures that the column names which are passed
140140
will be expressed in the VALUES clause of the :class:`_sql.Insert`
141141
construct automatically.
142142

‎doc/build/tutorial/data_select.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Selecting Rows with Core or ORM
1414

1515
For both Core and ORM, the :func:`_sql.select` function generates a
1616
:class:`_sql.Select` construct which is used for all SELECT queries.
17-
Passed to methods like :meth:`_future.Connection.execute` in Core and
17+
Passed to methods like :meth:`_engine.Connection.execute` in Core and
1818
:meth:`_orm.Session.execute` in ORM, a SELECT statement is emitted in the
1919
current transaction and the result rows available via the returned
2020
:class:`_engine.Result` object.

0 commit comments

Comments
 (0)