From: Mike Bayer Date: Sun, 13 Sep 2020 17:15:29 +0000 (-0400) Subject: Update session.execute() and related documentation X-Git-Tag: rel_1_4_0b1~99^2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5de0688fae17f60dc3c9e1c2782c9f6c8a621291;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Update session.execute() and related documentation The docs here were completely out of date and referred to behaviors that are no longer true, behaviors that are deprecated, etc. For the moment, take out all the verbiage so that nothing incorrect is present. New ORM documentation will need to be constructed to support this statement. Change-Id: I4782aebb6443ceb68752c3b52b574fd30658ebc9 --- diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index afab8e7b4e..3da05e7430 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -1011,11 +1011,11 @@ class Connection(Connectable): return self.execute(object_, *multiparams, **params).scalar() - def execute(self, object_, *multiparams, **params): + def execute(self, statement, *multiparams, **params): r"""Executes a SQL statement construct and returns a :class:`_engine.CursorResult`. - :param object: The statement to be executed. May be + :param statement: The statement to be executed. May be one of: * a plain string (deprecated) @@ -1085,7 +1085,7 @@ class Connection(Connectable): """ - if isinstance(object_, util.string_types): + if isinstance(statement, util.string_types): util.warn_deprecated_20( "Passing a string to Connection.execute() is " "deprecated and will be removed in version 2.0. Use the " @@ -1095,7 +1095,7 @@ class Connection(Connectable): ) return self._exec_driver_sql( - object_, + statement, multiparams, params, _EMPTY_EXECUTION_OPTS, @@ -1103,10 +1103,10 @@ class Connection(Connectable): ) try: - meth = object_._execute_on_connection + meth = statement._execute_on_connection except AttributeError as err: util.raise_( - exc.ObjectNotExecutableError(object_), replace_context=err + exc.ObjectNotExecutableError(statement), replace_context=err ) else: return meth(self, multiparams, params, _EMPTY_EXECUTION_OPTS) diff --git a/lib/sqlalchemy/future/engine.py b/lib/sqlalchemy/future/engine.py index dd72360eda..d2f609326a 100644 --- a/lib/sqlalchemy/future/engine.py +++ b/lib/sqlalchemy/future/engine.py @@ -255,7 +255,7 @@ class Connection(_LegacyConnection): r"""Executes a SQL statement construct and returns a :class:`_engine.Result`. - :param object: The statement to be executed. This is always + :param statement: The statement to be executed. This is always an object that is in both the :class:`_expression.ClauseElement` and :class:`_expression.Executable` hierarchies, including: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 535f030cf5..39e63296c1 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1434,95 +1434,29 @@ class Session(_SessionClassMethods): _add_event=None, **kw ): - r"""Execute a SQL expression construct or string statement within - the current transaction. + r"""Execute a SQL expression construct. - 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`. + Returns a :class:`_engine.Result` object representing + results of the statement execution. E.g.:: + from sqlalchemy import select result = session.execute( - user_table.select().where(user_table.c.id == 5) - ) - - :meth:`~.Session.execute` accepts any executable clause construct, - such as :func:`_expression.select`, - :func:`_expression.insert`, - :func:`_expression.update`, - :func:`_expression.delete`, and - :func:`_expression.text`. Plain SQL strings can be passed - as well, which in the case of :meth:`.Session.execute` only - will be interpreted the same as if it were passed via a - :func:`_expression.text` construct. That is, the following usage:: - - result = session.execute( - "SELECT * FROM user WHERE id=:param", - {"param":5} - ) - - is equivalent to:: - - from sqlalchemy import text - result = session.execute( - text("SELECT * FROM user WHERE id=:param"), - {"param":5} - ) + select(User).where(User.id == 5) + ) - The second positional argument to :meth:`.Session.execute` is an - optional parameter set. Similar to that of - :meth:`_engine.Connection.execute`, whether this is passed as a single - dictionary, or a sequence of dictionaries, determines whether the DBAPI - cursor's ``execute()`` or ``executemany()`` is used to execute the - statement. An INSERT construct may be invoked for a single row:: + The API contract of :meth:`_orm.Session.execute` is similar to that + of :meth:`_future.Connection.execute`, the :term:`2.0 style` version + of :class:`_future.Connection`. - result = session.execute( - users.insert(), {"id": 7, "name": "somename"}) - - or for multiple rows:: - - result = session.execute(users.insert(), [ - {"id": 7, "name": "somename7"}, - {"id": 8, "name": "somename8"}, - {"id": 9, "name": "somename9"} - ]) - - The statement is executed within the current transactional context of - this :class:`.Session`. The :class:`_engine.Connection` - which is used - to execute the statement can also be acquired directly by - calling the :meth:`.Session.connection` method. Both methods use - a rule-based resolution scheme in order to determine the - :class:`_engine.Connection`, - which in the average case is derived directly - from the "bind" of the :class:`.Session` itself, and in other cases - can be based on the :func:`.mapper` - and :class:`_schema.Table` objects passed to the method; see the - documentation for :meth:`.Session.get_bind` for a full description of - this scheme. - - The :meth:`.Session.execute` method does *not* invoke autoflush. - - 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 - autocommitting and does not have a transaction-dedicated - :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.CursorResult` - has - consumed all available data. This applies *only* when the - :class:`.Session` is configured with autocommit=True and no - transaction has been started. + .. versionchanged:: 1.4 the :meth:`_orm.Session.execute` method is + now the primary point of ORM statement execution when using + :term:`2.0 style` ORM usage. :param statement: An executable statement (i.e. an :class:`.Executable` expression - such as :func:`_expression.select`) or string SQL statement - to be executed. + such as :func:`_expression.select`). :param params: Optional dictionary, or list of dictionaries, containing @@ -1531,6 +1465,12 @@ class Session(_SessionClassMethods): "executemany" will be invoked. The keys in each dictionary must correspond to parameter names present in the statement. + :param execution_options: optional dictionary of execution options, + which will be associated with the statement execution. This + dictionary can provide a subset of the options that are accepted + by :meth:`_future.Connection.execution_options`, and may also + provide additional options understood only in an ORM context. + :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the @@ -1545,18 +1485,8 @@ class Session(_SessionClassMethods): :param \**kw: deprecated; use the bind_arguments dictionary - .. seealso:: - - :ref:`sqlexpression_toplevel` - Tutorial on using Core SQL - constructs. + :return: a :class:`_engine.Result` object. - :ref:`connections_toplevel` - Further information on direct - statement execution. - - :meth:`_engine.Connection.execute` - - core level statement execution - method, which is :meth:`.Session.execute` ultimately uses - in order to execute the statement. """ statement = coercions.expect(roles.CoerceTextStatementRole, statement) @@ -1657,7 +1587,13 @@ class Session(_SessionClassMethods): bind_arguments=None, **kw ): - """Like :meth:`~.Session.execute` but return a scalar result.""" + """Execute a statement and return a scalar result. + + Usage and parameters are the same as that of + :meth:`_orm.Session.execute`; the return result is a scalar Python + value. + + """ return self.execute( statement,