Merge branch 'master' into no-more-mandatory-buffer-size

Author: njsmith

ci.sh

@@ -120,7 +120,7 @@ else
 
     INSTALLDIR=$(python -c "import os, trio; print(os.path.dirname(trio.__file__))")
     cp ../setup.cfg $INSTALLDIR
-    pytest -W error -ra --junitxml=../test-results.xml --run-slow --faulthandler-timeout=60 ${INSTALLDIR} --cov="$INSTALLDIR" --cov-config=../.coveragerc --verbose
+    pytest -W error -r a --junitxml=../test-results.xml --run-slow ${INSTALLDIR} --cov="$INSTALLDIR" --cov-config=../.coveragerc --verbose
 
     # Disable coverage on 3.8 until we run 3.8 on Windows CI too
     #   https://github.com/python-trio/trio/pull/784#issuecomment-446438407

docs-requirements.txt

@@ -11,7 +11,7 @@ babel==2.7.0              # via sphinx
 certifi==2019.6.16        # via requests
 chardet==3.0.4            # via requests
 click==7.0                # via towncrier
-docutils==0.14            # via sphinx
+docutils==0.15            # via sphinx
 idna==2.8
 imagesize==1.1.0          # via sphinx
 immutables==0.9
@@ -21,12 +21,12 @@ markupsafe==1.1.1         # via jinja2
 outcome==1.0.0
 packaging==19.0           # via sphinx
 pygments==2.4.2           # via sphinx
-pyparsing==2.4.0          # via packaging
+pyparsing==2.4.1.1        # via packaging
 pytz==2019.1              # via babel
 requests==2.22.0          # via sphinx
 six==1.12.0               # via packaging
 sniffio==1.1.0
-snowballstemmer==1.2.1    # via sphinx
+snowballstemmer==1.9.0    # via sphinx
 sortedcontainers==2.1.0
 sphinx-rtd-theme==0.4.3
 sphinx==2.1.2

docs/source/contributing.rst

@@ -167,6 +167,14 @@ to get feedback on, feel free to submit it as a PR. (In this case it's
 traditional to start the PR title with ``[WIP]``, for "work in
 progress".)
 
+When you are submitting your PR, you can include ``Closes #123``,
+``Fixes: #123`` or
+`some variation <https://help.github.com/en/articles/closing-issues-using-keywords>`__
+in either your commit message or the PR description, in order to
+automatically close the referenced issue when the PR is merged.
+This keeps us closer to the desired state where each open issue reflects some
+work that still needs to be done.
+
 
 .. _pull-request-tests:
 

docs/source/history.rst

@@ -564,7 +564,7 @@ Upcoming breaking changes with warnings (i.e., stuff that in 0.2.0
 
   * We took the opportunity to refactor ``run_in_trio_thread`` and
     ``await_in_trio_thread`` into the new class
-    :class:`trio.BlockingTrioPortal`
+    ``trio.BlockingTrioPortal``
 
   * The hazmat function ``current_call_soon_thread_and_signal_safe``
     is being replaced by :class:`trio.hazmat.TrioToken`

docs/source/reference-core.rst

@@ -1109,7 +1109,7 @@ Using channels to pass values between tasks
 different tasks. They're particularly useful for implementing
 producer/consumer patterns.
 
-The channel API is defined by the abstract base classes
+The core channel API is defined by the abstract base classes
 :class:`trio.abc.SendChannel` and :class:`trio.abc.ReceiveChannel`.
 You can use these to implement your own custom channels, that do
 things like pass objects between processes or over the network. But in
@@ -1125,14 +1125,23 @@ inside a single process, and for that you can use
    what you use when you're looking for a queue. The main difference
    is that Trio splits the classic queue interface up into two
    objects. The advantage of this is that it makes it possible to put
-   the two ends in different processes, and that we can close the two
-   sides separately.
+   the two ends in different processes without rewriting your code,
+   and that we can close the two sides separately.
+
+`MemorySendChannel` and `MemoryReceiveChannel` also expose several
+more features beyond the core channel interface:
+
+.. autoclass:: MemorySendChannel
+   :members:
+
+.. autoclass:: MemoryReceiveChannel
+   :members:
 
 
 A simple channel example
 ++++++++++++++++++++++++
 
-Here's a simple example of how to use channels:
+Here's a simple example of how to use memory channels:
 
 .. literalinclude:: reference-core/channels-simple.py
 
@@ -1244,14 +1253,13 @@ program above:
 .. literalinclude:: reference-core/channels-mpmc-fixed.py
    :emphasize-lines: 7, 9, 10, 12, 13
 
-This example demonstrates using the :meth:`SendChannel.clone
-<trio.abc.SendChannel.clone>` and :meth:`ReceiveChannel.clone
-<trio.abc.ReceiveChannel.clone>` methods. What these do is create
-copies of our endpoints, that act just like the original – except that
-they can be closed independently. And the underlying channel is only
-closed after *all* the clones have been closed. So this completely
-solves our problem with shutdown, and if you run this program, you'll
-see it print its six lines of output and then exits cleanly.
+This example demonstrates using the `MemorySendChannel.clone` and
+`MemoryReceiveChannel.clone` methods. What these do is create copies
+of our endpoints, that act just like the original – except that they
+can be closed independently. And the underlying channel is only closed
+after *all* the clones have been closed. So this completely solves our
+problem with shutdown, and if you run this program, you'll see it
+print its six lines of output and then exits cleanly.
 
 Notice a small trick we use: the code in ``main`` creates clone
 objects to pass into all the child tasks, and then closes the original
@@ -1464,8 +1472,8 @@ for working with real, operating-system level,
 :mod:`threading`\-module-style threads. First, if you're in Trio but
 need to push some blocking I/O into a thread, there's
 :func:`run_sync_in_thread`. And if you're in a thread and need
-to communicate back with Trio, you can use a
-:class:`BlockingTrioPortal`.
+to communicate back with Trio, you can use
+:func:`trio.from_thread.run` and :func:`trio.from_thread.run_sync`.
 
 
 .. _worker-thread-limiting:
@@ -1603,14 +1611,15 @@ Putting blocking I/O into worker threads
 Getting back into the Trio thread from another thread
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: BlockingTrioPortal
-   :members:
+.. autofunction:: trio.from_thread.run
+
+.. autofunction:: trio.from_thread.run_sync
 
 This will probably be clearer with an example. Here we demonstrate how
 to spawn a child thread, and then use a :ref:`memory channel
 <channels>` to send messages between the thread and a Trio task:
 
-.. literalinclude:: reference-core/blocking-trio-portal-example.py
+.. literalinclude:: reference-core/from-thread-example.py
 
 
 Exceptions and warnings

docs/source/reference-core/blocking-trio-portal-example.py renamed to docs/source/reference-core/from-thread-example.py

@@ -1,29 +1,29 @@
 import trio
 
-def thread_fn(portal, receive_from_trio, send_to_trio):
+
+def thread_fn(receive_from_trio, send_to_trio):
     while True:
         # Since we're in a thread, we can't call methods on Trio
-        # objects directly -- so we use our portal to call them.
+        # objects directly -- so we use trio.from_thread to call them.
         try:
-            request = portal.run(receive_from_trio.receive)
+            request = trio.from_thread.run(receive_from_trio.receive)
         except trio.EndOfChannel:
-            portal.run(send_to_trio.aclose)
+            trio.from_thread.run(send_to_trio.aclose)
             return
         else:
             response = request + 1
-            portal.run(send_to_trio.send, response)
+            trio.from_thread.run(send_to_trio.send, response)
+
 
 async def main():
-    portal = trio.BlockingTrioPortal()
     send_to_thread, receive_from_trio = trio.open_memory_channel(0)
     send_to_trio, receive_from_thread = trio.open_memory_channel(0)
 
     async with trio.open_nursery() as nursery:
         # In a background thread, run:
         #   thread_fn(portal, receive_from_trio, send_to_trio)
         nursery.start_soon(
-            trio.run_sync_in_thread,
-            thread_fn, portal, receive_from_trio, send_to_trio
+            trio.run_sync_in_thread, thread_fn, receive_from_trio, send_to_trio
         )
 
         # prints "1"
@@ -40,4 +40,5 @@ async def main():
         # When we exit the nursery, it waits for the background thread to
         # exit.
 
+
 trio.run(main)

docs/source/reference-hazmat.rst

@@ -174,6 +174,26 @@ All environments provide the following functions:
    yourself afterwards.
 
 
+Unix-specific API
+-----------------
+
+`FdStream` supports wrapping Unix files (such as a pipe or TTY) as
+a stream.
+
+If you have two different file descriptors for sending and receiving,
+and want to bundle them together into a single bidirectional
+`~trio.abc.Stream`, then use `trio.StapledStream`::
+
+    bidirectional_stream = trio.StapledStream(
+        trio.hazmat.FdStream(write_fd),
+        trio.hazmat.FdStream(read_fd)
+    )
+
+.. autoclass:: FdStream
+   :show-inheritance:
+   :members:
+
+
 Kqueue-specific API
 -------------------
 
@@ -280,11 +300,11 @@ These transitions are accomplished using two function decorators:
    function).
 
    An example of where you'd use this is in implementing something
-   like :meth:`trio.BlockingTrioPortal.run`, which uses
+   like :func:`trio.from_thread.run`, which uses
    :meth:`TrioToken.run_sync_soon` to get into the Trio
    thread. :meth:`~TrioToken.run_sync_soon` callbacks are run with
    :exc:`KeyboardInterrupt` protection enabled, and
-   :meth:`~trio.BlockingTrioPortal.run` takes advantage of this to safely set up
+   :func:`trio.from_thread.run` takes advantage of this to safely set up
    the machinery for sending a response back to the original thread, but
    then uses :func:`disable_ki_protection` when entering the
    user-provided function.

docs/source/reference-io.rst

@@ -117,14 +117,19 @@ Abstract base classes
      - :class:`~trio.SocketListener`, :class:`~trio.SSLListener`
    * - :class:`SendChannel`
      - :class:`AsyncResource`
-     - :meth:`~SendChannel.send`, :meth:`~SendChannel.send_nowait`
+     - :meth:`~SendChannel.send`
      -
-     - :func:`~trio.open_memory_channel`
+     - `~trio.MemorySendChannel`
    * - :class:`ReceiveChannel`
      - :class:`AsyncResource`
-     - :meth:`~ReceiveChannel.receive`, :meth:`~ReceiveChannel.receive_nowait`
+     - :meth:`~ReceiveChannel.receive`
      - ``__aiter__``, ``__anext__``
-     - :func:`~trio.open_memory_channel`
+     - `~trio.MemoryReceiveChannel`
+   * - `Channel`
+     - `SendChannel`, `ReceiveChannel`
+     -
+     -
+     -
 
 .. autoclass:: trio.abc.AsyncResource
    :members:
@@ -165,6 +170,10 @@ Abstract base classes
    :members:
    :show-inheritance:
 
+.. autoclass:: trio.abc.Channel
+   :members:
+   :show-inheritance:
+
 .. currentmodule:: trio
 
 
@@ -394,6 +403,10 @@ Socket objects
          left in an unknown state – possibly open, and possibly
          closed. The only reasonable thing to do is to close it.
 
+   .. method:: is_readable
+
+      Check whether the socket is readable or not.
+
    .. method:: sendfile
 
       `Not implemented yet! <https://github.com/python-trio/trio/issues/45>`__

newsfragments/719.feature.rst

@@ -0,0 +1,6 @@
+We cleaned up the distinction between the "abstract channel interface"
+and the "memory channel" concrete implementation.
+`trio.abc.SendChannel` and `trio.abc.ReceiveChannel` have been slimmed
+down, `trio.MemorySendChannel` and `trio.MemoryReceiveChannel` are now
+public types that can be used in type hints, and there's a new
+`trio.abc.Channel` interface for future bidirectional channels.

newsfragments/760.feature.rst

@@ -0,0 +1,2 @@
+Trio sockets have a new method `~trio.socket.SocketType.is_readable` that allows
+you to check whether a socket is readable. This is useful for HTTP/1.1 clients.