Docs cleanup, cont.

Author: coleifer

docs/peewee/asyncio.rst

@@ -38,7 +38,7 @@ Example
 -------
 
 ``playhouse.pwasyncio`` contains the async database implementations. Typically
-this is the only thing you will need in order to use Peewee with asyncio:
+this is the only thing you need to use Peewee with asyncio:
 
 .. code-block:: python
 
@@ -110,14 +110,13 @@ performs I/O. Whenever a query executes, control switches to the event loop and
 the I/O coroutine is awaited like any other awaitable. Then the original call
 resumes with the result.
 
-This is real asyncio, NOT gevent-style concurrency. Nothing is
+This is real asyncio, not gevent-style concurrency. Nothing is
 monkey-patched, no sockets are wrapped, and the event loop is the ordinary
 asyncio loop running the rest of your application.
 
-To show how this works I'll walk through the following example, which uses two
-internal primitives ``greenlet_spawn`` (run sync code in a greenlet) and ``await_``
-(suspend the sync greenlet, passing control and a coroutine to the async
-parent).
+The following example uses two internal primitives, ``greenlet_spawn`` (run sync
+code in a greenlet) and ``await_`` (suspend the sync greenlet, passing control
+and a coroutine to the async parent).
 
 .. code-block:: python
 
@@ -147,7 +146,7 @@ When this runs:
    the bridge between sync and async python. Inside the new greenlet everything
    is synchronous, but it can yield coroutines to the async-world parent, which
    then awaits them on the loop.
-3. Inside the new greenlet we begin executing ``synchronous()`` (it does NOT know
+3. Inside the new greenlet we begin executing ``synchronous()`` (it does not know
    anything about asyncio). ``a_add(1, 2)`` creates a coroutine, which gets passed
    to ``await_()``.
 4. Inside ``await_()``, we *switch contexts* back to the parent (async world),
@@ -176,10 +175,9 @@ asynchronously:
 
 In your code you should never need to use ``greenlet_spawn()`` or ``await_()``
 directly. Peewee wraps all this in ``a``-prefixed methods and helpers so that the
-greenlet machinery remains an implementation detail, but it's worth taking a
-look at to understand what's going on. In short, Peewee uses greenlets to pass
-coroutines out of synchronous code, so they can be ``await``-ed, at the cost of
-two lightweight context switches.
+greenlet machinery remains an implementation detail. Peewee uses greenlets to
+pass coroutines out of synchronous code, so they can be ``await``-ed, at the cost
+of two lightweight context switches.
 
 Async Model Methods
 -------------------
@@ -341,7 +339,7 @@ For single-query operations, the async helpers are more direct:
    cursor = await query.aexecute()
 
    # Use a transaction:
-   async with db.atomic() as tx:
+   async with db.atomic():
        await db.run(User.create, name='Bob')
 
    # SELECT and return one model instance (raises DoesNotExist if none).
@@ -435,10 +433,8 @@ Explicit control is also available:
    # ... queries ...
    await db.aclose()      # Release connection back to pool.
 
-Each asyncio task gets its own connection from the pool. **Connections are not
-shared between tasks**. Each async task will have its own connection and
-transaction state - this prevents bugs that may occur when connections are
-shared and transactions end up interleaved across several running tasks.
+Each asyncio task gets its own connection and transaction state, so tasks never
+interleave each other's transactions.
 
 To shut down completely (e.g. during application teardown):
 
@@ -491,9 +487,8 @@ writes will not occur "faster", the bottleneck has merely been moved.
 Conversely, if you don't have that much load, the async wrapper adds complexity
 and overhead for no measurable benefit.
 
-To use SQLite in an async environment anyways, it is strongly recommended to
-use WAL-mode at a minimum, which allows multiple readers to co-exist with a
-single writer:
+To use SQLite in an async environment anyway, use WAL-mode at a minimum, which
+allows multiple readers to co-exist with a single writer:
 
 .. code-block:: python
 

docs/peewee/installation.rst

@@ -72,12 +72,12 @@ following drivers are supported out of the box:
 +-----------------------+----------------------------+--------------------------------------------+
 | MySQL (alternate)     | ``mysql-connector-python`` | :class:`.MySQLConnectorDatabase`           |
 +-----------------------+----------------------------+--------------------------------------------+
-| MariaDB (alternate)   | ``mariadb-connector``      | :class:`.MariaDBConnectorDatabase`         |
+| MariaDB (alternate)   | ``mariadb``                | :class:`.MariaDBConnectorDatabase`         |
 +-----------------------+----------------------------+--------------------------------------------+
 | CockroachDB           | ``psycopg`` (2 or 3)       | :class:`.CockroachDatabase`                |
 +-----------------------+----------------------------+--------------------------------------------+
 | Postgres (extensions) | ``psycopg`` (2 or 3)       | :class:`.PostgresqlExtDatabase`            |
 +-----------------------+----------------------------+--------------------------------------------+
 
-The three bolded rows cover the majority of deployments. All others are
+The bolded rows cover the majority of deployments. All others are
 optional; install their drivers when needed.

docs/peewee/query_builder.rst

@@ -6,8 +6,7 @@ Query Builder
 Peewee's high-level :class:`Model` and :class:`Field` APIs are built upon
 lower-level :class:`Table` and :class:`Column` counterparts. While these
 lower-level APIs are not documented in as much detail as their high-level
-counterparts, this document will present an overview with examples that should
-hopefully allow you to experiment.
+counterparts, this document will present an overview with worked examples.
 
 We'll use the following schema:
 
@@ -76,8 +75,8 @@ To select the first three notes and print their content, we can write:
     the row data, if you wish.
 
 Because we didn't specify any columns, all the columns we defined in the
-note's :class:`Table` constructor will be selected. This won't work for
-Reminder, as we didn't specify any columns at all.
+note's :class:`Table` constructor will be selected. ``Reminder`` declares no
+columns, so ``Reminder.select()`` emits ``SELECT * FROM "reminder"`` instead.
 
 To select all notes published in 2018 along with the name of the creator, we
 will use :meth:`~Select.join`. We'll also request that rows be returned
@@ -190,7 +189,7 @@ new row is returned):
         Note.content: 'meeeeowwww',
         Note.timestamp: datetime.datetime.now()}).execute()
 
-It is easy to bulk-insert data, just pass in either:
+To bulk-insert data, pass in either:
 
 * A list of dictionaries (all must have the same keys/columns).
 * A list of tuples, if the columns are specified explicitly.

docs/peewee/query_library.rst

@@ -299,7 +299,7 @@ this information?
 
 .. code-block:: sql
 
-    SELECT MAX(join_date) FROM members;
+    SELECT MAX(joindate) FROM members;
 
 .. code-block:: python
 
@@ -914,7 +914,7 @@ slots, sorted by the number of slots.
 
     SELECT facid, SUM(slots)
     FROM bookings
-    WHERE (date_trunc('month', starttime) = '2012-09-01'::dates)
+    WHERE (date_trunc('month', starttime) = '2012-09-01'::date)
     GROUP BY facid
     ORDER BY SUM(slots)
 
@@ -1090,7 +1090,7 @@ Postgres ONLY.
 .. code-block:: sql
 
     SELECT facid, date_part('month', starttime), SUM(slots)
-    FROM booking
+    FROM bookings
     WHERE date_part('year', starttime) = 2012
     GROUP BY ROLLUP(facid, date_part('month', starttime))
     ORDER BY facid, date_part('month', starttime)

docs/peewee/query_operators.rst

@@ -216,14 +216,12 @@ Now you can use these custom operators to build richer queries:
 Expressions
 -----------
 
-Peewee is designed to provide a simple, expressive, and pythonic way of
-constructing SQL queries. This section will provide a quick overview of some
-common types of expressions.
+This section gives an overview of common expression types.
 
 Two common types of objects that are composed to create expressions:
 
 * :class:`Field` instances
-* SQL aggregations and functions using :class:`fn`
+* SQL aggregations and functions using :func:`fn`
 
 We will assume a simple "User" model with fields for username and other things.
 It looks like this:
@@ -260,8 +258,8 @@ arbitrary depth:
    # User's username is either charlie or charles
    (User.username == 'charlie') | (User.username == 'charles')
 
-   # User is active and not a superuser.
-   (User.is_active & ~User.is_superuser)
+   # User is active and not an admin.
+   (User.is_active & ~User.is_admin)
 
 Comparisons can be used with functions as well:
 
@@ -286,7 +284,7 @@ Expressions allow us to do *atomic updates*:
    # when a user logs in we want to increment their login count:
    User.update(login_count=User.login_count + 1).where(User.id == user_id)
 
-Expressions can be used in all parts of a query, so experiment!
+Expressions can be used in all parts of a query.
 
 Row values
 ^^^^^^^^^^
@@ -368,10 +366,8 @@ parameters can be fields, values, subqueries, or even nested functions.
 Nesting function calls
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Suppose you need to want to get a list of all users whose username begins with
-*a*. There are a couple ways to do this, but one method might be to use some
-SQL functions like *LOWER* and *SUBSTR*. To use arbitrary SQL functions, use
-the special :func:`fn` object to construct queries:
+To get all users whose username begins with *a*, use SQL functions like *LOWER*
+and *SUBSTR* via the :func:`fn` object:
 
 .. code-block:: python
 
@@ -388,8 +384,7 @@ the special :func:`fn` object to construct queries:
 SQL Helper
 ----------
 
-There are times when you may want to simply pass in some arbitrary sql. You can
-do this using the special :class:`SQL` class. One use-case is when
+To pass arbitrary SQL, use the special :class:`SQL` class. One use-case is
 referencing an alias:
 
 .. code-block:: python
@@ -404,7 +399,7 @@ referencing an alias:
    # Now we will order by the count, which was aliased to "ct"
    query = query.order_by(SQL('ct'))
 
-   # You could, of course, also write this as:
+   # Or equivalently:
    query = query.order_by(fn.COUNT(Tweet.id))
 
 There are two ways to execute hand-crafted SQL statements with peewee:

docs/peewee/quickstart.rst

@@ -4,8 +4,7 @@ Quickstart
 ==========
 
 This guide walks through defining a schema, writing rows, and reading them
-back. It takes about ten minutes. Every concept introduced here is covered in
-depth in the following documents.
+back.
 
 .. tip::
    Follow along in an interactive Python session.
@@ -40,8 +39,6 @@ classes map to tables.
            default=datetime.datetime.now,
            index=True)
 
-Three things to notice:
-
 * ``BaseModel`` exists only to carry the ``database`` setting. Every subclass
   inherits it automatically.
 * Peewee adds an auto-incrementing integer ``id`` primary key to any model
@@ -106,7 +103,7 @@ if no match is found:
    print(user.id, user.username)
 
 Retrieve multiple rows with :meth:`~Model.select`. The result is a lazy
-query - rows are fetched only when you iterate:
+query. Rows are fetched only when you iterate:
 
 .. code-block:: python
 
@@ -134,9 +131,7 @@ Join to combine data from related tables in a single query:
 
 .. code-block:: python
 
-   # Fetch each tweet alongside its author's username.
-   # Without the join, accessing tweet.user.username would issue
-   # an extra query per tweet - see the N+1 section in Relationships.
+   # Select each tweet with its author in one query.
    query = (Tweet
             .select(Tweet, User)
             .join(User)
@@ -177,7 +172,7 @@ Working with Existing databases
 -------------------------------
 
 If you have an existing database, peewee can generate models using :ref:`pwiz`.
-For example to generate models for a Postgres database named ``blog_db``:
+For example to generate models for a Postgres database named ``blog``:
 
 .. code-block:: shell
 

docs/peewee/relationships.rst

@@ -8,17 +8,6 @@ across tables. This document explains how Peewee models those links, what
 happens under the hood when you traverse them, and how to write queries that
 cross table boundaries efficiently.
 
-By the end of this document you will understand:
-
-* How :class:`ForeignKeyField` behaves at runtime, not just at schema
-  definition time.
-* What a back-reference is and when to use one.
-* What the N+1 problem is and how to recognise it.
-* How to write joins, including multi-table and self-referential joins.
-* How many-to-many relationships are modelled.
-* When to use eager loading (:meth:`~ModelSelect.with_related`) instead of a
-  join.
-
 
 Model Definitions
 -----------------
@@ -204,8 +193,7 @@ that user's tweets:
    alice-2
    alice-3
 
-Taking a closer look at ``alice.tweets``, we can see that it is just a simple
-pre-filtered ``SELECT`` query:
+``alice.tweets`` is a pre-filtered ``SELECT`` query:
 
 .. code-block:: pycon
 
@@ -292,28 +280,7 @@ Joins
 
 A SQL join combines columns from two or more tables into a single result set.
 Peewee's :meth:`~ModelSelect.join` method generates the appropriate ``JOIN``
-clause and reconstructs the model graph automatically:
-
-.. code-block:: python
-
-   TweetUser = User.alias()  # We are going to reference the User table twice,
-                             # so we need an alias.
-
-   query = (Favorite
-            .select(Favorite, User, Tweet, TweetUser)
-            .join_from(Favorite, User)  # Get user who owns this Favorite.
-            .join_from(Favorite, Tweet)  # What tweet was favorite-d.
-            .join_from(Tweet, TweetUser))  # What user created the tweet.
-
-   # Single query is issued.
-   for fav in query:
-       print(fav.user.username, 'likes', fav.tweet.content,
-             'by', fav.tweet.user.username)
-
-   # alice likes bob-2 by bob
-   # bob likes alice-3 by alice
-   # carol likes alice-1 by alice
-   # carol likes alice-3 by alice
+clause and reconstructs the model graph automatically.
 
 Simple joins
 ^^^^^^^^^^^^
@@ -452,8 +419,7 @@ corresponding attributes.
    # bob -> bob-1
    # bob -> bob-2
 
-To make it a bit more obvious that it's doing the correct thing, we can ask
-Peewee to return the rows as dictionaries.
+Returning the rows as dictionaries makes this clearer:
 
 .. code-block:: python
 
@@ -611,8 +577,7 @@ Iterating over the query, we can see each user and their latest tweet.
    # alice -> alice-3
    # bob -> bob-2
 
-There are a couple things you may not have seen before in the code we used to
-create the query in this section:
+Three things in this query:
 
 * We used :meth:`~ModelSelect.join_from` to explicitly specify the join
   context. We wrote ``.join_from(Tweet, User)``, which is equivalent to
@@ -847,8 +812,8 @@ the corresponding instance in the reconstructed graph:
 .. code-block:: python
 
    name = Case(User.username, [
-       ('u1', 'User One'),
-       ('u2', 'User Two')], 'Someone Else')
+       ('alice', 'Alice A.'),
+       ('bob', 'Bob B.')], 'Someone Else')
 
    query = (Tweet
             .select(Tweet.content, name.alias('display').bind_to(User))

docs/peewee/schema.rst

@@ -36,10 +36,8 @@ Indexes declared in ``Meta.indexes`` and via :meth:`Model.add_index` are
 created along with the table.
 
 .. note::
-   A common pattern in web applications is to call ``db.create_tables(MODELS, safe=True)``
-   once at startup. This ensures all tables exist without failing on an already-
-   initialized database. It does **not** apply schema changes - for that, see
-   :ref:`migrations`.
+   ``create_tables`` creates missing tables but does **not** apply schema
+   changes to existing ones. For that, see :ref:`migrations`.
 
 Dropping Tables
 ---------------
@@ -55,8 +53,8 @@ multiple times. To disable this, pass ``safe=False``.
 
    db.drop_tables([User, Tweet, Favorite], safe=False)
 
-Pass ``cascade=True`` (Postgresql and MySQL) to let the database handle
-dependency ordering:
+Pass ``cascade=True`` on Postgresql to drop dependent objects and let the
+database handle ordering (MySQL parses but ignores CASCADE):
 
 .. code-block:: python
 
@@ -113,8 +111,8 @@ Schema Migrations
 -----------------
 
 Peewee does not include a built-in migration system. For schema changes in an
-existing deployment - adding columns, dropping columns, renaming tables,
-modifying indexes - use one of the following approaches.
+existing deployment (adding columns, dropping columns, renaming tables,
+modifying indexes), use one of the following approaches.
 
 Playhouse migrate module
 ^^^^^^^^^^^^^^^^^^^^^^^^^