Update documentation for aiocontextvars 0.2

Author: fantix

README.rst

@@ -57,10 +57,7 @@ Installation
 
 .. code-block:: console
 
-    pip install gino aiocontextvars
-
-(aiocontextvars_ is an optional dependency recommended for most users. It will
-be replaced_ by contextvars_, and it is not needed in upcoming `Python 3.7`_)
+    pip install gino
 
 
 Showcase
@@ -248,7 +245,6 @@ hiring_!
 .. _`hire us`: https://decentfox.com/
 .. _`Become a patron`: https://www.patreon.com/fantixking
 .. _hiring: https://www.zhipin.com/gongsi/c6e283cf57f2d9361nF92NS7GA~~.html
-.. _aiocontextvars: https://github.com/fantix/aiocontextvars
 .. _contextvars: https://github.com/MagicStack/contextvars
 .. _replaced: https://github.com/MagicStack/contextvars/issues/2
 .. _`Python 3.7`: https://docs.python.org/3.7/library/contextvars.html

docs/engine.rst

@@ -273,22 +273,12 @@ new head of the stack.
 
 .. tip::
 
-    By context, we are actually referring to the context concept in either
-    `aiocontextvars <https://github.com/fantix/aiocontextvars>`_ the optional
-    dependency or `contextvars
-    <https://docs.python.org/3.7/library/contextvars.html>`_ the new module in
-    upcoming Python 3.7. Simply speaking, you may treat a function call chain
-    including awaited :class:`~asyncio.Task` created in the chain as in the
-    same context, something like a thread local in asyncio.
-
-.. note::
-
-    And that is to say, `aiocontextvars
-    <https://github.com/fantix/aiocontextvars>`_ is a required dependency for
-    ``reuse`` to work correctly in Python 3.6 - actually ``reuse`` is the
-    reason for introducing context in the first place. Without context, the
-    stack is always empty for any :meth:`~gino.engine.GinoEngine.acquire` thus
-    no one could reuse any raw connection at all.
+    By context, we are actually referring to the context concept in
+    `contextvars <https://docs.python.org/3.7/library/contextvars.html>`_ the
+    new module in Python 3.7, and its partial backport `aiocontextvars
+    <https://github.com/fantix/aiocontextvars>`_. Simply speaking, you may
+    treat a series of function calls in a chain as in the same context, even if
+    there is an ``await``. It's something like a thread local in asyncio.
 
 :class:`~gino.engine.GinoConnection` (2) may be created through
 ``acquire(reuse=True)`` too - because the stack is empty before (2), there is
@@ -519,11 +509,3 @@ at the creation of :class:`~gino.api.Gino` instance. Therefore, any
 :class:`~sqlalchemy.sql.expression.Executable` object has the ``gino``
 property for implicit execution. Similarly, the execution methods calls the
 corresponding ones on the ``bind`` of the ``db`` instance.
-
-.. warning::
-
-    The assumption for code above to run as expected is having
-    `aiocontextvars <https://github.com/fantix/aiocontextvars>`_ installed on
-    Python 3.6, or directly using Python 3.7. Or else, nested implicit
-    executions will always run in a different new connection. This may be not
-    so important here, but it is crucial for transactions.

docs/faq.rst

@@ -41,22 +41,19 @@ available on :func:`~gino.create_engine` or :meth:`db.set_bind()
     engine = await gino.create_engine(..., ssl=True)
 
 
-Transaction cannot rollback changes?
-------------------------------------
+What is aiocontextvars and what does it do?
+-------------------------------------------
 
-As for now, make sure `aiocontextvars
-<https://github.com/fantix/aiocontextvars>`_ is installed in order to use
-contextual transactions like this::
+It is a partial backport of the new built-in module `contextvars
+<https://docs.python.org/3.7/library/contextvars.html>`_ introduced in Python
+3.7. In Python 3.5 and 3.6, ``aiocontextvars`` patches ``loop.create_task()` to
+copy context from caller as a workaround to simulate the same behavior. This is
+also under discussion in upstream backport project, please read more here:
+https://github.com/MagicStack/contextvars/issues/2
 
-    async with db.transaction():
-        await MyModel.create(name='xxx')
+If you are using Python 3.7, then ``aiocontextvars`` does nothing at all.
 
-Or else if you'd prefer not to install an additional dependency, you'll have to
-modify the code to explicitly use the correct connection::
+.. note::
 
-    async with db.transaction() as tx:
-        await MyModel.create(name='xxx', bind=tx.connection)
-
-.. tip::
-
-    Since GINO 0.7.4, ``aiocontextvars`` became a required dependency.
+    This answer is for GINO 0.8 and later, please check earlier versions of
+    this documentation if you are using GINO 0.7.

docs/tutorial.rst

@@ -27,32 +27,14 @@ code run faster, if not slower. Please read :doc:`why` for more information.
 Installation
 ------------
 
-.. note::
-
-    GINO optionally depends on aiocontextvars_ for sharing connection between
-    method calls or chained coroutines without passing the connection object
-    over and over again. It is highly recommended for most projects, unless you
-    truly need a bare environment and handle connections manually.
-
-.. important::
-
-    aiocontextvars_ will be replaced by `contextvars
-    <https://github.com/MagicStack/contextvars>`__ once it `supports asyncio
-    <https://github.com/MagicStack/contextvars/issues/2>`_. And neither will be
-    needed in Python 3.7 which is delivered with a builtin `contextvars
-    <https://docs.python.org/3.7/library/contextvars.html>`__ module.
-
-.. _aiocontextvars: https://github.com/fantix/aiocontextvars
-
-
 Stable release
 ^^^^^^^^^^^^^^
 
 To install GINO, run this command in your terminal:
 
 .. code-block:: console
 
-    $ pip install gino aiocontextvars
+    $ pip install gino
 
 This is the preferred method to install GINO, as it will always install the
 most recent stable release.