Method begin

lib/sqlalchemy/orm/session.py:1897–1950

Begin a transaction, or nested transaction, on this :class:`.Session`, if one is not already begun. The :class:`_orm.Session` object features **autobegin** behavior, so that normally it is not necessary to call the :meth:`_orm.Session.begin` method explicitly

(self, nested: bool = False)

        return self._transaction

    def begin(self, nested: bool = False) -> SessionTransaction:
        """Begin a transaction, or nested transaction,
        on this :class:`.Session`, if one is not already begun.

        The :class:`_orm.Session` object features **autobegin** behavior,
        so that normally it is not necessary to call the
        :meth:`_orm.Session.begin`
        method explicitly. However, it may be used in order to control
        the scope of when the transactional state is begun.

        When used to begin the outermost transaction, an error is raised
        if this :class:`.Session` is already inside of a transaction.

        :param nested: if True, begins a SAVEPOINT transaction and is
         equivalent to calling :meth:`~.Session.begin_nested`. For
         documentation on SAVEPOINT transactions, please see
         :ref:`session_begin_nested`.

        :return: the :class:`.SessionTransaction` object.  Note that
         :class:`.SessionTransaction`
         acts as a Python context manager, allowing :meth:`.Session.begin`
         to be used in a "with" block.  See :ref:`session_explicit_begin` for
         an example.

        .. seealso::

            :ref:`session_autobegin`

            :ref:`unitofwork_transaction`

            :meth:`.Session.begin_nested`


        """

        trans = self._transaction
        if trans is None:
            trans = self._autobegin_t(begin=True)

            if not nested:
                return trans

        assert trans is not None

        if nested:
            trans = trans._begin(nested=nested)
            assert self._transaction is trans
            self._nested_transaction = trans
        else:
            raise sa_exc.InvalidRequestError(
                "A transaction is already begun on this Session."
            )

        return trans  # needed for __enter__/__exit__ hook

    def begin_nested(self) -> SessionTransaction:
        """Begin a "nested" transaction on this Session, e.g. SAVEPOINT.