Merge pull request #71 from oremanj/deprecations

Missing bits from #69

Author: pquentin

README.rst

@@ -23,10 +23,10 @@
  trio-asyncio
 ==============
 
-**Trio-Asyncio** is a re-implementation of the ``asyncio`` mainloop on top of
+**trio-asyncio** is a re-implementation of the ``asyncio`` mainloop on top of
 Trio.
 
-Trio-Asyncio requires at least Python 3.5.3. It is tested on recent versions of
+trio-asyncio requires at least Python 3.5.3. It is tested on recent versions of
 3.5, 3.6, 3.7, 3.8, and nightly.
 
 +++++++++++
@@ -42,7 +42,7 @@ On the other hand, there are quite a few asyncio-enhanced libraries. You
 *really* don't want to re-invent any wheels in your project.
 
 Thus, being able to use asyncio libraries from Trio is useful.
-Trio-Asyncio enables you to do that, and more.
+trio-asyncio enables you to do that, and more.
 
 --------------------------------------
  Transparent vs. explicit translation
@@ -65,34 +65,27 @@ Trio-Asyncio's documentation is too large for a README.
 
 For further information, `see the manual on readthedocs <http://trio-asyncio.readthedocs.io/en/latest/>`_.
 
-++++++++++++++++++++++
- Hacking trio-asyncio
-++++++++++++++++++++++
+++++++++++++++
+ Contributing
+++++++++++++++
 
------------
- Licensing
------------
+Like Trio, trio-asyncio is licensed under both the MIT and Apache licenses.
+Submitting a patch or pull request implies your acceptance of these licenses.
 
-Like trio, trio-asyncio is licensed under both the MIT and Apache licenses.
-Submitting patches or pull requests imply your acceptance of these licenses.
+Testing is done with ``pytest``. Test coverage is pretty thorough; please
+keep it that way when adding new code.
 
----------
- Patches
----------
+See the `Trio contributor guide
+<https://trio.readthedocs.io/en/stable/contributing.html>`__ for much
+more detail on how to get involved.
 
-are accepted gladly.
-
----------
- Testing
----------
-
-As in trio, testing is done with ``pytest``.
-
-Test coverage is close to 100%. Please keep it that way.
+Contributors are requested to follow our `code of conduct
+<https://trio.readthedocs.io/en/stable/code-of-conduct.html>`__ in all
+project spaces.
 
 ++++++++
  Author
 ++++++++
 
-Matthias Urlichs <matthias@urlichs.de>
-
+trio-asyncio was originally written by Matthias Urlichs <matthias@urlichs.de>.
+It is now maintained by the `Trio project <https://github.com/python-trio>`_.

docs/source/history.rst

@@ -14,13 +14,14 @@ Features
 - `trio_asyncio` now contains an `allow_asyncio` wrapper which allows you to
   seamlessly mix asyncio and trio semantics::
 
-      from trio_asyncio import run
-      @allow_asyncio
+      import asyncio
+      import trio
+      from trio_asyncio import run, allow_asyncio
       async def main():
           print("Sleeping 1")
-	  await asyncio.sleep(1)
+          await asyncio.sleep(1)
           print("Sleeping 2")
-	  await trio.sleep(1)
+          await trio.sleep(1)
       run(allow_asyncio, main)
 
   The problem with this solution is that Trio's cancellations will no

docs/source/index.rst

@@ -8,7 +8,7 @@
 trio-asyncio: A re-implementation of the asyncio mainloop on top of Trio
 ========================================================================
 
-trio-asyncio is *the* library of choice for a Python program that
+trio-asyncio is the library of choice for a Python program that
 contains both `Trio <https://trio.readthedocs.io/en/stable/>`__ and
 `asyncio` code.
 

docs/source/principles.rst

@@ -148,7 +148,7 @@ though Trio supports them on earlier Pythons using a backport package.
  Event loop implementations
 ----------------------------
 
-An asyncio event loop may generally be interrupted and restarted at any
+A stock asyncio event loop may be interrupted and restarted at any
 time, simply by making repeated calls to :meth:`run_until_complete()
 <asyncio.loop.run_until_complete>`.
 Trio, however, requires one long-running main loop. trio-asyncio bridges

docs/source/usage.rst

@@ -209,7 +209,7 @@ context variables.)
 However, this feature should generally not be necessary, because you
 should know whether each function in your program is asyncio-flavored
 or Trio-flavored. (The two have different semantics, especially
-surroudning cancellation.) It's provided mainly so that your
+surrounding cancellation.) It's provided mainly so that your
 trio-asyncio program can safely depend on libraries that use `sniffio`
 to support both flavors. It can also be helpful if you want to assert
 that you're in the mode you think you're in, using ::

newsfragments/64.removal.rst

@@ -0,0 +1,14 @@
+The non-underscore-prefixed names of trio-asyncio submodules (``trio_asyncio.loop``,
+``trio_asyncio.adapter``, etc) have been deprecated; public names should be
+imported from ``trio_asyncio`` directly.
+
+``trio_asyncio.current_policy``, ``trio_asyncio.TrioChildWatcher``,
+and ``trio_asyncio.TrioPolicy`` have been deprecated with no
+replacement.  ``current_policy`` is no longer used at all, and the
+other two are singletons that can't be customized so there's no reason
+to make them publicly visible.
+
+A number of functions which were already documented as deprecated now
+raise the new :exc:`~trio_asyncio.TrioAsyncioDeprecationWarning` where
+previously they provided either no runtime warning or a generic
+:exc:`DeprecationWarning`.

trio_asyncio/_async.py

@@ -22,15 +22,15 @@ def default_exception_handler(self, context):
         Rationale:
 
         In traditional asyncio, there frequently is no context which the
-        exception is supposed to effect.
+        exception is supposed to affect.
 
-        trio-asyncio, however, collects the loop and all its tasks in a
-        Trio nursery. Thus the context which must be aborted, and thus in which
-        the error needs to be raised, is known and can easily be controlled
-        by the programmer.
+        trio-asyncio, however, collects the loop and all its tasks in
+        a Trio nursery. This means the context in which the error should
+        be raised is known and can easily be controlled by the programmer.
 
         For maximum compatibility, this default handler is only used in
         asynchronous loops.
+
         """
         # TODO: add context.get('handle') to the exception
 

trio_asyncio/_base.py

@@ -222,7 +222,7 @@ async def run_aio_coroutine(self, coro):
         then return or raise its result.
 
         Cancelling the current Trio scope will cancel the coroutine,
-        which it will experience as a single thrown `asyncio.CancelledError`
+        which will throw a single `asyncio.CancelledError` into the coroutine
         (just like the usual asyncio behavior). If the coroutine then
         exits with a `~asyncio.CancelledError` exception, the call to
         :meth:`run_aio_coroutine` will raise `trio.Cancelled`.