From: Mike Bayer Date: Sun, 26 Apr 2020 14:59:34 +0000 (-0400) Subject: Documentation updates for ResultProxy -> Result X-Git-Tag: rel_1_4_0b1~354 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f247bb20007190ae7aa89929c02c03317b1e6876;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Documentation updates for ResultProxy -> Result This is based off of I8091919d45421e3f53029b8660427f844fee0228 and includes all documentation-only changes as a separate merge, once the parent is merged. Change-Id: I711adea23df0f9f0b1fe7c76210bd2de6d31842d --- diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst index 15f77b2909..9c7d5fa55d 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 28826e3897..9ba038cf5f 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 266b20e089..d4dfd18ce5 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 5bc8381819..6c100282ee 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 f384b3cf1d..f87d78c1a5 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 cbcb39df06..874eb50234 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 2b39d96b11..f636d7cf1a 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 f0a01d7ea1..18e4d12692 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 8bda0371aa..233768f42b 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") - + >>> 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 b7260403af..f6d50023b8 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 7a7b875365..a20aab8d8b 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 38f3fa6111..dca7b9a001 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 61cb19c34e..a85a36bb71 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) ... - + 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) ... - + 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 769fbb06a2..1eaf63ff34 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 dbc8c5e7fe..38d819a09e 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 8419cf9202..39bf285450 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 09e700b5cd..a2066de4ab 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 2ab707b8ab..af271c56c0 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 e078774759..49d9af9661 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 a3a9cc489c..fe0abf0bb6 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 04491911e9..aa29214981 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 286c83cc40..a066846f7f 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 5409b9d7f3..f5d1918603 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 6ec520a3e7..1fc299ceca 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 4ca715dd32..b053b8d960 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 16aa98adb7..3558a7c5fd 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -313,7 +313,7 @@ def identity_key(*args, **kwargs): (, (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 4d14497c1c..625183db31 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 4ed01375e0..3dc4e917cf 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 d8b5a16263..e7c1f3f77e 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 02addc6f58..5e832e9345 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 43e906032f..17f9e1579a 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