]> git.ipfire.org Git - thirdparty/sqlalchemy/sqlalchemy.git/commitdiff
Docs: simplify language use for "Working with Transactions and the DBAPI"
authorlonkeknol <alex@resilium.group>
Thu, 27 Jun 2024 13:03:30 +0000 (09:03 -0400)
committerMike Bayer <mike_mp@zzzcomputing.com>
Thu, 27 Jun 2024 13:09:20 +0000 (09:09 -0400)
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: #<issue number>` 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: #<issue number>` 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

index 4eeee79e592333d3120c7de4950cd801752c045f..cd1ec0c2cfbe46ab8b81120e117b8e3405ca327c 100644 (file)
@@ -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