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
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
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:
``.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
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
"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",
}
zzzeeksphinx_module_prefixes = {
"_sa": "sqlalchemy",
"_engine": "sqlalchemy.engine",
+ "_result": "sqlalchemy.engine",
+ "_row": "sqlalchemy.engine",
"_schema": "sqlalchemy.schema",
"_types": "sqlalchemy.types",
"_expression": "sqlalchemy.sql.expression",
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.
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
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.
Connection / Engine API
=======================
-.. autoclass:: BaseResult
+.. autoclass:: BaseCursorResult
+ :members:
+
+.. autoclass:: ChunkedIteratorResult
:members:
.. autoclass:: Connection
.. 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:
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).
.. autofunction:: sqlalchemy.future.select
-.. autoclass:: sqlalchemy.future.Result
- :members:
- :inherited-members:
- :exclude-members: memoized_attribute, memoized_instancemethod
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::
: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`::
>>> 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
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
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
.. seealso::
- :attr:`_engine.ResultProxy.rowcount`
+ :attr:`_engine.CursorResult.rowcount`
CAST Support
... 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
... 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::
``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`
* ``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
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::
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
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:
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",
*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)
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:
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::
)
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
.. versionadded: 1.4
- :param result: :class:`_engine.ResultProxy` generated by the execution
+ :param result: :class:`_engine.CursorResult` generated by the execution
.
"""
: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
"""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.
"""
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):
"""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)
"""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.
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
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
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
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):
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.
* 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
: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.
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.
]
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`.
"""
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`.
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
: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
(<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
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.
"""
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
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.
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
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
:meth:`.UpdateBase.returning`
- :attr:`_engine.ResultProxy.returned_defaults`
+ :attr:`_engine.CursorResult.returned_defaults`
"""
self._return_defaults = cols or True
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.
"""
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
``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
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.
"""
# 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
in_(stmt.c.keyed2_b, row)
-class ResultProxyTest(fixtures.TablesTest):
+class CursorResultTest(fixtures.TablesTest):
__backend__ = True
@classmethod
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
