diff options
31 files changed, 164 insertions, 82 deletions
diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst index 15f77b290..9c7d5fa55 100644 --- a/doc/build/changelog/migration_14.rst +++ b/doc/build/changelog/migration_14.rst @@ -354,15 +354,15 @@ is fully compatible with ``ResultProxy`` and includes many new features, that are now applied to both Core and ORM results equally, including methods such as: - :meth:`.Result.one` + :meth:`_engine.Result.one` - :meth:`.Result.one_or_none` + :meth:`_engine.Result.one_or_none` - :meth:`.Result.partitions` + :meth:`_engine.Result.partitions` - :meth:`.Result.columns` + :meth:`_engine.Result.columns` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` When using Core, the object returned is an instance of :class:`.CursorResult`, which continues to feature the same API features as ``ResultProxy`` regarding diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 28826e389..9ba038cf5 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -484,7 +484,7 @@ to a series of statement executions in the same way as that of session = Session() - result = session.execution_options(stream_per=100).execute(stmt) + result = session.execution_options(stream_results=True).execute(stmt) The calling signature for the ``.execute()`` method itself will work in a "positional only" spirit, since :pep:`570` is only available in @@ -511,7 +511,7 @@ So that an execution may look like:: result = connection.execute(table.insert(), {"foo": "bar"}, isolation_level='AUTOCOMMIT') - result = session.execute(stmt, stream_per=100) + result = session.execute(stmt, stream_results=True) .. _change_result_20_core: @@ -534,7 +534,7 @@ upon, where the more refined ORM-like methods ``.all()``, ``.one()`` and ``.first()`` will now also be how Core retrieves rows, replacing the cursor-like ``.fetchall()``, ``.fetchone()`` methods. The notion of receiving "chunks" of a result at a time will be standardized across both -systems using new methods ``.partitions`` and ``.chunks()`` which will behave similarly to +systems using a new method ``.partitions()`` which will behave similarly to ``.fetchmany()``, but will work in terms of iterators. These new methods will be available from the "Result" object that is similar to @@ -567,10 +567,6 @@ equally:: result.partitions(size=1000) # partition result into iterator of lists of size N - # same, but do it using a server side cursor if the driver supports - # it - result = conn.execution_options(stream_per=1000).chunks() - # limiting columns diff --git a/doc/build/conf.py b/doc/build/conf.py index 266b20e08..d4dfd18ce 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -103,6 +103,8 @@ autodocmods_convert_modname = { "sqlalchemy.sql.base": "sqlalchemy.sql.expression", "sqlalchemy.event.base": "sqlalchemy.event", "sqlalchemy.engine.base": "sqlalchemy.engine", + "sqlalchemy.engine.row": "sqlalchemy.engine", + "sqlalchemy.engine.cursor": "sqlalchemy.engine", "sqlalchemy.engine.result": "sqlalchemy.engine", "sqlalchemy.util._collections": "sqlalchemy.util", } @@ -118,6 +120,8 @@ autodocmods_convert_modname_w_class = { zzzeeksphinx_module_prefixes = { "_sa": "sqlalchemy", "_engine": "sqlalchemy.engine", + "_result": "sqlalchemy.engine", + "_row": "sqlalchemy.engine", "_schema": "sqlalchemy.schema", "_types": "sqlalchemy.types", "_expression": "sqlalchemy.sql.expression", diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 5bc838181..6c100282e 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -57,11 +57,11 @@ end of the block. The :class:`_engine.Connection`, is a **proxy** object for an actual DBAPI connection. The DBAPI connection is retrieved from the connection pool at the point at which :class:`_engine.Connection` is created. -The object returned is known as :class:`_engine.ResultProxy`, which +The object returned is known as :class:`_engine.CursorResult`, which references a DBAPI cursor and provides methods for fetching rows similar to that of the DBAPI cursor. The DBAPI cursor will be closed -by the :class:`_engine.ResultProxy` when all of its result rows (if any) are -exhausted. A :class:`_engine.ResultProxy` that returns no rows, such as that of +by the :class:`_engine.CursorResult` when all of its result rows (if any) are +exhausted. A :class:`_engine.CursorResult` that returns no rows, such as that of an UPDATE statement (without any returned rows), releases cursor resources immediately upon construction. @@ -74,7 +74,7 @@ pooling mechanism issues a ``rollback()`` call on the DBAPI connection so that any transactional state or locks are removed, and the connection is ready for its next use. -.. deprecated:: 2.0 The :class:`_engine.ResultProxy` object is replaced in SQLAlchemy +.. deprecated:: 2.0 The :class:`_engine.CursorResult` object is replaced in SQLAlchemy 2.0 with a newly refined object known as :class:`_future.Result`. Our example above illustrated the execution of a textual SQL string, which @@ -346,9 +346,9 @@ Overall, the usage of "bound metadata" has three general effects: In both "connectionless" examples, the :class:`~sqlalchemy.engine.Connection` is created behind the scenes; the -:class:`~sqlalchemy.engine.ResultProxy` returned by the ``execute()`` +:class:`~sqlalchemy.engine.CursorResult` returned by the ``execute()`` call references the :class:`~sqlalchemy.engine.Connection` used to issue -the SQL statement. When the :class:`_engine.ResultProxy` is closed, the underlying +the SQL statement. When the :class:`_engine.CursorResult` is closed, the underlying :class:`_engine.Connection` is closed for us, resulting in the DBAPI connection being returned to the pool with transactional resources removed. @@ -645,7 +645,10 @@ The above will respond to ``create_engine("mysql+foodialect://")`` and load the Connection / Engine API ======================= -.. autoclass:: BaseResult +.. autoclass:: BaseCursorResult + :members: + +.. autoclass:: ChunkedIteratorResult :members: .. autoclass:: Connection @@ -663,15 +666,34 @@ Connection / Engine API .. autoclass:: ExceptionContext :members: +.. autoclass:: FrozenResult + :members: + +.. autoclass:: IteratorResult + :members: + .. autoclass:: LegacyRow :members: +.. autoclass:: MergedResult + :members: + .. autoclass:: NestedTransaction :members: -.. autoclass:: ResultProxy +.. autoclass:: Result :members: :inherited-members: + :exclude-members: memoized_attribute, memoized_instancemethod + + +.. autoclass:: CursorResult + :members: + :inherited-members: + :exclude-members: memoized_attribute, memoized_instancemethod + +.. autoclass:: LegacyCursorResult + :members: .. autoclass:: Row :members: diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst index f384b3cf1..f87d78c1a 100644 --- a/doc/build/core/defaults.rst +++ b/doc/build/core/defaults.rst @@ -233,15 +233,15 @@ inline. When the statement is executed with a single set of parameters (that is, it is not an "executemany" style execution), the returned -:class:`~sqlalchemy.engine.ResultProxy` will contain a collection accessible -via :meth:`_engine.ResultProxy.postfetch_cols` which contains a list of all +:class:`~sqlalchemy.engine.CursorResult` will contain a collection accessible +via :meth:`_engine.CursorResult.postfetch_cols` which contains a list of all :class:`~sqlalchemy.schema.Column` objects which had an inline-executed default. Similarly, all parameters which were bound to the statement, including all Python and SQL expressions which were pre-executed, are present in the -:meth:`_engine.ResultProxy.last_inserted_params` or -:meth:`_engine.ResultProxy.last_updated_params` collections on -:class:`~sqlalchemy.engine.ResultProxy`. The -:attr:`_engine.ResultProxy.inserted_primary_key` collection contains a list of primary +:meth:`_engine.CursorResult.last_inserted_params` or +:meth:`_engine.CursorResult.last_updated_params` collections on +:class:`~sqlalchemy.engine.CursorResult`. The +:attr:`_engine.CursorResult.inserted_primary_key` collection contains a list of primary key values for the row inserted (a list so that single-column and composite- column primary keys are represented in the same format). diff --git a/doc/build/core/future.rst b/doc/build/core/future.rst index cbcb39df0..874eb5023 100644 --- a/doc/build/core/future.rst +++ b/doc/build/core/future.rst @@ -20,7 +20,3 @@ SQLAlchemy 2.0 Future (Core) .. autofunction:: sqlalchemy.future.select -.. autoclass:: sqlalchemy.future.Result - :members: - :inherited-members: - :exclude-members: memoized_attribute, memoized_instancemethod diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst index 2b39d96b1..f636d7cf1 100644 --- a/doc/build/faq/performance.rst +++ b/doc/build/faq/performance.rst @@ -175,7 +175,7 @@ ORM query if the wrong :class:`_schema.Column` objects are used in a complex que pulling in additional FROM clauses that are unexpected. On the other hand, a fast call to ``fetchall()`` at the DBAPI level, but then -slowness when SQLAlchemy's :class:`_engine.ResultProxy` is asked to do a ``fetchall()``, +slowness when SQLAlchemy's :class:`_engine.CursorResult` is asked to do a ``fetchall()``, may indicate slowness in processing of datatypes, such as unicode conversions and similar:: diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index f0a01d7ea..18e4d1269 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -79,7 +79,7 @@ SQL expressions and strings can be executed via the :class:`~sqlalchemy.orm.session.Session` within its transactional context. This is most easily accomplished using the :meth:`~.Session.execute` method, which returns a -:class:`~sqlalchemy.engine.ResultProxy` in the same manner as an +:class:`~sqlalchemy.engine.CursorResult` in the same manner as an :class:`~sqlalchemy.engine.Engine` or :class:`~sqlalchemy.engine.Connection`:: diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst index 8bda0371a..233768f42 100644 --- a/doc/build/orm/session_transaction.rst +++ b/doc/build/orm/session_transaction.rst @@ -424,7 +424,7 @@ on the target connection, a warning is emitted:: >>> session = Session(eng) >>> session.execute("select 1") - <sqlalchemy.engine.result.ResultProxy object at 0x1017a6c50> + <sqlalchemy.engine.result.CursorResult object at 0x1017a6c50> >>> session.connection(execution_options={'isolation_level': 'SERIALIZABLE'}) sqlalchemy/orm/session.py:310: SAWarning: Connection is already established for the given bind; execution_options ignored diff --git a/lib/sqlalchemy/dialects/firebird/base.py b/lib/sqlalchemy/dialects/firebird/base.py index b7260403a..f6d50023b 100644 --- a/lib/sqlalchemy/dialects/firebird/base.py +++ b/lib/sqlalchemy/dialects/firebird/base.py @@ -49,12 +49,12 @@ of hanging transactions is a non-fully consumed result set, i.e.:: row = result.fetchone() return -Where above, the ``ResultProxy`` has not been fully consumed. The +Where above, the ``CursorResult`` has not been fully consumed. The connection will be returned to the pool and the transactional state rolled back once the Python garbage collector reclaims the objects which hold onto the connection, which often occurs asynchronously. The above use case can be alleviated by calling ``first()`` on the -``ResultProxy`` which will fetch the first row and immediately close +``CursorResult`` which will fetch the first row and immediately close all remaining cursor/connection resources. RETURNING support diff --git a/lib/sqlalchemy/dialects/firebird/fdb.py b/lib/sqlalchemy/dialects/firebird/fdb.py index 7a7b87536..a20aab8d8 100644 --- a/lib/sqlalchemy/dialects/firebird/fdb.py +++ b/lib/sqlalchemy/dialects/firebird/fdb.py @@ -29,7 +29,7 @@ accept every argument that Kinterbasdb does. the usage of "cursor.rowcount" with the Kinterbasdb dialect, which SQLAlchemy ordinarily calls upon automatically after any UPDATE or DELETE statement. When disabled, SQLAlchemy's - ResultProxy will return -1 for result.rowcount. The rationale here is + CursorResult will return -1 for result.rowcount. The rationale here is that Kinterbasdb requires a second round trip to the database when .rowcount is called - since SQLA's resultproxy automatically closes the cursor after a non-result-returning statement, rowcount must be diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 38f3fa611..dca7b9a00 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -469,7 +469,7 @@ This setting is currently hardcoded. .. seealso:: - :attr:`_engine.ResultProxy.rowcount` + :attr:`_engine.CursorResult.rowcount` CAST Support diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index 61cb19c34..a85a36bb7 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -206,7 +206,7 @@ reflection process as follows:: ... referring = Table('referring', meta, ... autoload=True, autoload_with=conn) ... - <sqlalchemy.engine.result.ResultProxy object at 0x101612ed0> + <sqlalchemy.engine.result.CursorResult object at 0x101612ed0> The above process would deliver to the :attr:`_schema.MetaData.tables` collection @@ -228,7 +228,7 @@ dialect-specific argument to both :class:`_schema.Table` as well as ... autoload_with=conn, ... postgresql_ignore_search_path=True) ... - <sqlalchemy.engine.result.ResultProxy object at 0x1016126d0> + <sqlalchemy.engine.result.CursorResult object at 0x1016126d0> We will now have ``test_schema.referred`` stored as schema-qualified:: diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index 769fbb06a..1eaf63ff3 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -23,7 +23,7 @@ psycopg2-specific keyword arguments which are accepted by ``connection.cursor('some name')``, which has the effect that result rows are not immediately pre-fetched and buffered after statement execution, but are instead left on the server and only retrieved as needed. SQLAlchemy's - :class:`~sqlalchemy.engine.ResultProxy` uses special row-buffering + :class:`~sqlalchemy.engine.CursorResult` uses special row-buffering behavior when this feature is enabled, such that groups of 100 rows at a time are fetched over the wire to reduce conversational overhead. Note that the :paramref:`.Connection.execution_options.stream_results` @@ -137,7 +137,7 @@ in addition to those not specific to DBAPIs: * ``max_row_buffer`` - when using ``stream_results``, an integer value that specifies the maximum number of rows to buffer at a time. This is - interpreted by the :class:`.BufferedRowResultProxy`, and if omitted the + interpreted by the :class:`.BufferedRowCursorResult`, and if omitted the buffer will grow to ultimately store 1000 rows at a time. .. versionchanged:: 1.4 The ``max_row_buffer`` size can now be greater than diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index dbc8c5e7f..38d819a09 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -558,9 +558,9 @@ names are still addressable*:: 1 Therefore, the workaround applied by SQLAlchemy only impacts -:meth:`_engine.ResultProxy.keys` and :meth:`.Row.keys()` in the public API. In +:meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` in the public API. In the very specific case where an application is forced to use column names that -contain dots, and the functionality of :meth:`_engine.ResultProxy.keys` and +contain dots, and the functionality of :meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` is required to return these dotted names unmodified, the ``sqlite_raw_colnames`` execution option may be provided, either on a per-:class:`_engine.Connection` basis:: diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 8419cf920..39bf28545 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -40,6 +40,10 @@ from .interfaces import ExceptionContext # noqa from .interfaces import ExecutionContext # noqa from .interfaces import TypeCompiler # noqa from .mock import create_mock_engine +from .result import ChunkedIteratorResult # noqa +from .result import FrozenResult # noqa +from .result import IteratorResult # noqa +from .result import MergedResult # noqa from .result import Result # noqa from .result import result_tuple # noqa from .row import BaseRow # noqa diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 09e700b5c..a2066de4a 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -977,7 +977,7 @@ class Connection(Connectable): def execute(self, object_, *multiparams, **params): r"""Executes a SQL statement construct and returns a - :class:`_engine.ResultProxy`. + :class:`_engine.CursorResult`. :param object: The statement to be executed. May be one of: @@ -1319,7 +1319,7 @@ class Connection(Connectable): self, statement, parameters=None, execution_options=None ): r"""Executes a SQL statement construct and returns a - :class:`_engine.ResultProxy`. + :class:`_engine.CursorResult`. :param statement: The statement str to be executed. Bound parameters must use the underlying DBAPI's paramstyle, such as "qmark", @@ -1380,7 +1380,7 @@ class Connection(Connectable): *args ): """Create an :class:`.ExecutionContext` and execute, returning - a :class:`_engine.ResultProxy`.""" + a :class:`_engine.CursorResult`.""" if execution_options: dialect.set_exec_execution_options(self, execution_options) @@ -1516,12 +1516,12 @@ class Connection(Connectable): assert not self._is_future assert not context._is_future_result - # ResultProxy already exhausted rows / has no rows. + # CursorResult already exhausted rows / has no rows. # close us now if result._soft_closed: self.close() else: - # ResultProxy will close this Connection when no more + # CursorResult will close this Connection when no more # rows to fetch. result._autoclose_connection = True except BaseException as e: @@ -2350,10 +2350,10 @@ class Engine(Connectable, log.Identified): that the :class:`_engine.Connection` will be closed when the operation is complete. When set to ``True``, it indicates the :class:`_engine.Connection` is in "single use" mode, where the - :class:`_engine.ResultProxy` returned by the first call to + :class:`_engine.CursorResult` returned by the first call to :meth:`_engine.Connection.execute` will close the :class:`_engine.Connection` when - that :class:`_engine.ResultProxy` has exhausted all result rows. + that :class:`_engine.CursorResult` has exhausted all result rows. .. seealso:: @@ -2465,16 +2465,16 @@ class Engine(Connectable, log.Identified): ) def execute(self, statement, *multiparams, **params): """Executes the given construct and returns a - :class:`_engine.ResultProxy`. + :class:`_engine.CursorResult`. The arguments are the same as those used by :meth:`_engine.Connection.execute`. Here, a :class:`_engine.Connection` is acquired using the :meth:`_engine.Engine.connect` method, and the statement executed - with that connection. The returned :class:`_engine.ResultProxy` + with that connection. The returned :class:`_engine.CursorResult` is flagged - such that when the :class:`_engine.ResultProxy` is exhausted and its + such that when the :class:`_engine.CursorResult` is exhausted and its underlying cursor is closed, the :class:`_engine.Connection` created here will also be closed, which allows its associated DBAPI connection diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index 2ab707b8a..af271c56c 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -243,7 +243,7 @@ class ConnectionEvents(event.Events): .. versionadded: 1.4 - :param result: :class:`_engine.ResultProxy` generated by the execution + :param result: :class:`_engine.CursorResult` generated by the execution . """ @@ -298,7 +298,7 @@ class ConnectionEvents(event.Events): :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed - as they will be needed by the :class:`_engine.ResultProxy`. + as they will be needed by the :class:`_engine.CursorResult`. :param statement: string SQL statement, as passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index e07877475..49d9af966 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -1250,7 +1250,7 @@ class ExecutionContext(object): """Return the DBAPI ``cursor.rowcount`` value, or in some cases an interpreted value. - See :attr:`_engine.ResultProxy.rowcount` for details on this. + See :attr:`_engine.CursorResult.rowcount` for details on this. """ @@ -1298,7 +1298,7 @@ class Connectable(object): def execute(self, object_, *multiparams, **params): """Executes the given construct and returns a """ - """:class:`_engine.ResultProxy`.""" + """:class:`_engine.CursorResult`.""" raise NotImplementedError() def scalar(self, object_, *multiparams, **params): diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index a3a9cc489..fe0abf0bb 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -585,9 +585,15 @@ class Result(InPlaceGenerative): """Return a callable object that will produce copies of this :class:`.Result` when invoked. + The callable object returned is an instance of + :class:`_engine.FrozenResult`. + This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method - will consume the result fully. + will consume the result fully. When the :class:`_engine.FrozenResult` + is retrieved from a cache, it can be called any number of times where + it will produce a new :class:`_engine.Result` object each time + against its stored set of rows. """ return FrozenResult(self) @@ -596,7 +602,7 @@ class Result(InPlaceGenerative): """Merge this :class:`.Result` with other compatible result objects. - The object returned is an instance of :class:`.MergedResult`, + The object returned is an instance of :class:`_engine.MergedResult`, which will be composed of iterators from the given result objects. @@ -1009,6 +1015,30 @@ class Result(InPlaceGenerative): class FrozenResult(object): + """Represents a :class:`.Result` object in a "frozen" state suitable + for caching. + + The :class:`_engine.FrozenResult` object is returned from the + :meth:`_engine.Result.freeze` method of any :class:`_engine.Result` + object. + + A new iterable :class:`.Result` object is generatged from a fixed + set of data each time the :class:`.FrozenResult` is invoked as + a callable:: + + + result = connection.execute(query) + + frozen = result.freeze() + + r1 = frozen() + r2 = frozen() + # ... etc + + .. versionadded:: 1.4 + + """ + def __init__(self, result): self.metadata = result._metadata._for_freeze() self._post_creational_filter = result._post_creational_filter @@ -1030,6 +1060,13 @@ class FrozenResult(object): class IteratorResult(Result): + """A :class:`.Result` that gets data from a Python iterator of + :class:`.Row` objects. + + .. versionadded:: 1.4 + + """ + def __init__(self, cursor_metadata, iterator): self._metadata = cursor_metadata self.iterator = iterator @@ -1061,6 +1098,20 @@ class IteratorResult(Result): class ChunkedIteratorResult(IteratorResult): + """An :class:`.IteratorResult` that works from an iterator-producing callable. + + The given ``chunks`` argument is a function that is given a number of rows + to return in each chunk, or ``None`` for all rows. The function should + then return an un-consumed iterator of lists, each list of the requested + size. + + The function can be called at any time again, in which case it should + continue from the same result set but adjust the chunk size as given. + + .. versionadded:: 1.4 + + """ + def __init__(self, cursor_metadata, chunks): self._metadata = cursor_metadata self.chunks = chunks @@ -1074,6 +1125,15 @@ class ChunkedIteratorResult(IteratorResult): class MergedResult(IteratorResult): + """A :class:`_engine.Result` that is merged from any number of + :class:`_engine.Result` objects. + + Returned by the :meth:`_engine.Result.merge` method. + + .. versionadded:: 1.4 + + """ + closed = False def __init__(self, cursor_metadata, results): diff --git a/lib/sqlalchemy/ext/horizontal_shard.py b/lib/sqlalchemy/ext/horizontal_shard.py index 04491911e..aa2921498 100644 --- a/lib/sqlalchemy/ext/horizontal_shard.py +++ b/lib/sqlalchemy/ext/horizontal_shard.py @@ -120,14 +120,14 @@ class ShardedQuery(Query): class ShardedResult(object): - """A value object that represents multiple :class:`_engine.ResultProxy` + """A value object that represents multiple :class:`_engine.CursorResult` objects. This is used by the :meth:`.ShardedQuery._execute_crud` hook to return - an object that takes the place of the single :class:`_engine.ResultProxy`. + an object that takes the place of the single :class:`_engine.CursorResult`. Attribute include ``result_proxies``, which is a sequence of the - actual :class:`_engine.ResultProxy` objects, + actual :class:`_engine.CursorResult` objects, as well as ``aggregate_rowcount`` or ``rowcount``, which is the sum of all the individual rowcount values. diff --git a/lib/sqlalchemy/future/engine.py b/lib/sqlalchemy/future/engine.py index 286c83cc4..a066846f7 100644 --- a/lib/sqlalchemy/future/engine.py +++ b/lib/sqlalchemy/future/engine.py @@ -30,7 +30,7 @@ class Connection(_LegacyConnection): * The result object returned for results is the :class:`_future.Result` object. This object has a slightly different API and behavior than the - prior :class:`_engine.ResultProxy` object. + prior :class:`_engine.CursorResult` object. * The object has :meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback` methods which commit or roll back diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 5409b9d7f..f5d191860 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -1747,7 +1747,7 @@ class SessionEvents(event.Events): :meth:`_query.Query.update`. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. - * ``result`` the :class:`_engine.ResultProxy` + * ``result`` the :class:`_engine.CursorResult` returned as a result of the bulk UPDATE operation. @@ -1783,7 +1783,7 @@ class SessionEvents(event.Events): was called upon. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. - * ``result`` the :class:`_engine.ResultProxy` + * ``result`` the :class:`_engine.CursorResult` returned as a result of the bulk DELETE operation. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 6ec520a3e..1fc299cec 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -3497,7 +3497,7 @@ class Query(Generative): ] def instances(self, result_proxy, context=None): - """Return an ORM result given a :class:`_engine.ResultProxy` and + """Return an ORM result given a :class:`_engine.CursorResult` and :class:`.QueryContext`. """ diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 4ca715dd3..b053b8d96 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1128,7 +1128,7 @@ class Session(_SessionClassMethods): r"""Execute a SQL expression construct or string statement within the current transaction. - Returns a :class:`_engine.ResultProxy` representing + Returns a :class:`_engine.CursorResult` representing results of the statement execution, in the same manner as that of an :class:`_engine.Engine` or :class:`_engine.Connection`. @@ -1196,7 +1196,7 @@ class Session(_SessionClassMethods): The :meth:`.Session.execute` method does *not* invoke autoflush. - The :class:`_engine.ResultProxy` returned by the :meth:`.Session. + The :class:`_engine.CursorResult` returned by the :meth:`.Session. execute` method is returned with the "close_with_result" flag set to true; the significance of this flag is that if this :class:`.Session` is @@ -1204,7 +1204,7 @@ class Session(_SessionClassMethods): :class:`_engine.Connection` available, a temporary :class:`_engine.Connection` is established for the statement execution, which is closed (meaning, - returned to the connection pool) when the :class:`_engine.ResultProxy` + returned to the connection pool) when the :class:`_engine.CursorResult` has consumed all available data. This applies *only* when the :class:`.Session` is configured with autocommit=True and no diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 16aa98adb..3558a7c5f 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -313,7 +313,7 @@ def identity_key(*args, **kwargs): (<class '__main__.MyClass'>, (1, 2), None) :param class: mapped class (must be a positional argument) - :param row: :class:`.Row` row returned by a :class:`_engine.ResultProxy` + :param row: :class:`.Row` row returned by a :class:`_engine.CursorResult` (must be given as a keyword arg) :param identity_token: optional identity token diff --git a/lib/sqlalchemy/sql/crud.py b/lib/sqlalchemy/sql/crud.py index 4d14497c1..625183db3 100644 --- a/lib/sqlalchemy/sql/crud.py +++ b/lib/sqlalchemy/sql/crud.py @@ -40,7 +40,7 @@ def _get_crud_params(compiler, stmt, compile_state, **kw): Also generates the Compiled object's postfetch, prefetch, and returning column collections, used for default handling and ultimately - populating the ResultProxy's prefetch_cols() and postfetch_cols() + populating the CursorResult's prefetch_cols() and postfetch_cols() collections. """ diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index 4ed01375e..3dc4e917c 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -345,7 +345,7 @@ class UpdateBase( Upon execution, the values of the columns to be returned are made available via the result set and can be iterated using - :meth:`_engine.ResultProxy.fetchone` and similar. + :meth:`_engine.CursorResult.fetchone` and similar. For DBAPIs which do not natively support returning values (i.e. cx_oracle), SQLAlchemy will approximate this behavior at the result level so that a reasonable @@ -547,7 +547,7 @@ class ValuesBase(UpdateBase): True, indicating that the statement will not attempt to fetch the "last inserted primary key" or other defaults. The statement deals with an arbitrary number of rows, so the - :attr:`_engine.ResultProxy.inserted_primary_key` + :attr:`_engine.CursorResult.inserted_primary_key` accessor does not apply. @@ -684,7 +684,7 @@ class ValuesBase(UpdateBase): added to any existing RETURNING clause, provided that :meth:`.UpdateBase.returning` is not used simultaneously. The column values will then be available on the result using the - :attr:`_engine.ResultProxy.returned_defaults` accessor as a dictionary + :attr:`_engine.CursorResult.returned_defaults` accessor as a dictionary , referring to values keyed to the :class:`_schema.Column` object as well as @@ -715,7 +715,7 @@ class ValuesBase(UpdateBase): 3. It can be called against any backend. Backends that don't support RETURNING will skip the usage of the feature, rather than raising an exception. The return value of - :attr:`_engine.ResultProxy.returned_defaults` will be ``None`` + :attr:`_engine.CursorResult.returned_defaults` will be ``None`` :meth:`.ValuesBase.return_defaults` is used by the ORM to provide an efficient implementation for the ``eager_defaults`` feature of @@ -732,7 +732,7 @@ class ValuesBase(UpdateBase): :meth:`.UpdateBase.returning` - :attr:`_engine.ResultProxy.returned_defaults` + :attr:`_engine.CursorResult.returned_defaults` """ self._return_defaults = cols or True @@ -922,7 +922,7 @@ class Insert(ValuesBase): True, indicating that the statement will not attempt to fetch the "last inserted primary key" or other defaults. The statement deals with an arbitrary number of rows, so the - :attr:`_engine.ResultProxy.inserted_primary_key` + :attr:`_engine.CursorResult.inserted_primary_key` accessor does not apply. """ @@ -1064,7 +1064,7 @@ class Update(DMLWhereBase, ValuesBase): the ``default`` keyword will be compiled 'inline' into the statement and not pre-executed. This means that their values will not be available in the dictionary returned from - :meth:`_engine.ResultProxy.last_updated_params`. + :meth:`_engine.CursorResult.last_updated_params`. :param preserve_parameter_order: if True, the update statement is expected to receive parameters **only** via the @@ -1189,7 +1189,7 @@ class Update(DMLWhereBase, ValuesBase): ``default`` keyword will be compiled 'inline' into the statement and not pre-executed. This means that their values will not be available in the dictionary returned from - :meth:`_engine.ResultProxy.last_updated_params`. + :meth:`_engine.CursorResult.last_updated_params`. .. versionchanged:: 1.4 the :paramref:`_expression.update.inline` parameter diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index d8b5a1626..e7c1f3f77 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -159,7 +159,7 @@ def outparam(key, type_=None): The ``outparam`` can be used like a regular function parameter. The "output" value will be available from the - :class:`~sqlalchemy.engine.ResultProxy` object via its ``out_parameters`` + :class:`~sqlalchemy.engine.CursorResult` object via its ``out_parameters`` attribute, which returns a dictionary containing the values. """ diff --git a/test/orm/inheritance/test_basic.py b/test/orm/inheritance/test_basic.py index 02addc6f5..5e832e934 100644 --- a/test/orm/inheritance/test_basic.py +++ b/test/orm/inheritance/test_basic.py @@ -2549,7 +2549,7 @@ class OptimizedLoadTest(fixtures.MappedTest): # columns in order to do the lookup. # # note this test can't fail when the fix is missing unless - # ResultProxy._key_fallback no longer allows a non-matching column + # CursorResult._key_fallback no longer allows a non-matching column # lookup without warning or raising. base, sub = self.tables.base, self.tables.sub diff --git a/test/sql/test_deprecations.py b/test/sql/test_deprecations.py index 43e906032..17f9e1579 100644 --- a/test/sql/test_deprecations.py +++ b/test/sql/test_deprecations.py @@ -1070,7 +1070,7 @@ class KeyTargetingTest(fixtures.TablesTest): in_(stmt.c.keyed2_b, row) -class ResultProxyTest(fixtures.TablesTest): +class CursorResultTest(fixtures.TablesTest): __backend__ = True @classmethod |