From 5baf033b8ce0e244f297ca597c0deda1fe34ffd7 Mon Sep 17 00:00:00 2001 From: lonkeknol Date: Thu, 27 Jun 2024 09:03:30 -0400 Subject: [PATCH] Docs: simplify language use for "Working with Transactions and the DBAPI" This is my first pull request to sqlalchemy. It changes the writing style of two paragraphs in the unified tutorial [here](https://docs.sqlalchemy.org/en/20/tutorial/dbapi_transactions.html#working-with-transactions-and-the-dbapi). My goals were to. 1. Make them easier to read 2. Not change the meaning of the text. 3. Get feedback on whether this type of contribution is considered useful for sqlalchemy. If this is a useful type of contribution, it might be good to discuss some general guidelines for me to adhere to as I continue. For instance: - Prefer using present simple tense - Remove superfluous words where possible - Keep the pull requests to one or two h2 sections at a time, to make the review easier This pull request is: - [x] A documentation / typographical / small typing error fix - Good to go, no issue or tests are needed - [ ] A short code fix - please include the issue number, and create an issue if none exists, which must include a complete example of the issue. one line code fixes without an issue and demonstration will not be accepted. - Please include: `Fixes: #` in the commit message - please include tests. one line code fixes without tests will not be accepted. - [ ] A new feature implementation - please include the issue number, and create an issue if none exists, which must include a complete example of how the feature would look. - Please include: `Fixes: #` in the commit message - please include tests. I'm curious to hear what you all think. **Have a nice day!** Closes: #11541 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/11541 Pull-request-sha: 3179690e6a5b47de99a4486a7a15cffbfacd380b Change-Id: I9b47f6ce4fd00c44c4b0e19957acf250f5e46d2f (cherry picked from commit fc2cb4496d35c0b8bb7d59aa74b553f07210eded) --- doc/build/tutorial/dbapi_transactions.rst | 34 +++++++++++------------ 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/build/tutorial/dbapi_transactions.rst b/doc/build/tutorial/dbapi_transactions.rst index 4eeee79e59..cd1ec0c2cf 100644 --- a/doc/build/tutorial/dbapi_transactions.rst +++ b/doc/build/tutorial/dbapi_transactions.rst @@ -11,32 +11,32 @@ Working with Transactions and the DBAPI -With the :class:`_future.Engine` object ready to go, we may now proceed -to dive into the basic operation of an :class:`_future.Engine` and -its primary interactive endpoints, the :class:`_future.Connection` and -:class:`_engine.Result`. We will additionally introduce the ORM's -:term:`facade` for these objects, known as the :class:`_orm.Session`. +With the :class:`_future.Engine` object ready to go, we can +dive into the basic operation of an :class:`_future.Engine` and +its primary endpoints, the :class:`_future.Connection` and +:class:`_engine.Result`. We'll also introduce the ORM's :term:`facade` +for these objects, known as the :class:`_orm.Session`. .. container:: orm-header **Note to ORM readers** - When using the ORM, the :class:`_future.Engine` is managed by another - object called the :class:`_orm.Session`. The :class:`_orm.Session` in - modern SQLAlchemy emphasizes a transactional and SQL execution pattern that - is largely identical to that of the :class:`_future.Connection` discussed - below, so while this subsection is Core-centric, all of the concepts here - are essentially relevant to ORM use as well and is recommended for all ORM + When using the ORM, the :class:`_future.Engine` is managed by the + :class:`_orm.Session`. The :class:`_orm.Session` in modern SQLAlchemy + emphasizes a transactional and SQL execution pattern that is largely + identical to that of the :class:`_future.Connection` discussed below, + so while this subsection is Core-centric, all of the concepts here + are relevant to ORM use as well and is recommended for all ORM learners. The execution pattern used by the :class:`_future.Connection` - will be contrasted with that of the :class:`_orm.Session` at the end + will be compared to the :class:`_orm.Session` at the end of this section. As we have yet to introduce the SQLAlchemy Expression Language that is the -primary feature of SQLAlchemy, we will make use of one simple construct within -this package called the :func:`_sql.text` construct, which allows us to write -SQL statements as **textual SQL**. Rest assured that textual SQL in -day-to-day SQLAlchemy use is by far the exception rather than the rule for most -tasks, even though it always remains fully available. +primary feature of SQLAlchemy, we'll use a simple construct within +this package called the :func:`_sql.text` construct, to write +SQL statements as **textual SQL**. Rest assured that textual SQL is the +exception rather than the rule in day-to-day SQLAlchemy use, but it's +always available. .. rst-class:: core-header -- 2.47.2