Merge remote-tracking branch 'origin/master' into cancelstatus

.readthedocs.yml

@@ -3,7 +3,7 @@ formats:
   - htmlzip
   - epub
 
-requirements_file: ci/rtd-requirements.txt
+requirements_file: docs-requirements.txt
 
 python:
   version: 3.5

.travis.yml

@@ -27,7 +27,7 @@ matrix:
     - python: 3.8-dev
 
 script:
-  - ci/ci.sh
+  - ./ci.sh
 
 branches:
   except:

azure-pipelines.yml

@@ -34,7 +34,7 @@ jobs:
     - bash: |
         set -ex
         env | sort
-        sudo docker run -e SYSTEM_JOBIDENTIFIER="$SYSTEM_JOBIDENTIFIER" -e CODECOV_TOKEN="$CODECOV_TOKEN" -v "$PWD:/t" ubuntu:rolling /bin/bash -c "set -ex; cd /t; apt update; apt install -y python3.7-dev python3-virtualenv git build-essential curl; python3.7 -m virtualenv -p python3.7 venv; source venv/bin/activate; source ci/ci.sh"
+        sudo docker run -e SYSTEM_JOBIDENTIFIER="$SYSTEM_JOBIDENTIFIER" -e CODECOV_TOKEN="$CODECOV_TOKEN" -v "$PWD:/t" ubuntu:rolling /bin/bash -c "set -ex; cd /t; apt update; apt install -y python3.7-dev python3-virtualenv git build-essential curl; python3.7 -m virtualenv -p python3.7 venv; source venv/bin/activate; source ci.sh"
 
 - job: 'Windows'
   pool:
@@ -67,7 +67,7 @@ jobs:
   steps:
   - task: NuGetToolInstaller@0
 
-  - bash: ci/ci.sh
+  - bash: ./ci.sh
     displayName: "Run the actual tests"
 
   - task: PublishTestResults@2
@@ -97,7 +97,7 @@ jobs:
 #     inputs:
 #       versionSpec: '$(python.version)'
 #
-#   - bash: ci/ci.sh
+#   - bash: ci.sh
 #     displayName: "Run the actual tests"
 #
 #   - task: PublishTestResults@2
@@ -123,7 +123,7 @@ jobs:
     inputs:
       versionSpec: '$(python.version)'
 
-  - bash: ci/ci.sh
+  - bash: ./ci.sh
     displayName: "Run the actual tests"
 
   - task: PublishTestResults@2

ci/ci.sh → ci.sh

@@ -102,7 +102,7 @@ python setup.py sdist --formats=zip
 python -m pip install dist/*.zip
 
 if [ "$CHECK_DOCS" = "1" ]; then
-    python -m pip install -r ci/rtd-requirements.txt
+    python -m pip install -r docs-requirements.txt
     towncrier --yes  # catch errors in newsfragments
     cd docs
     # -n (nit-picky): warn on missing references
@@ -119,6 +119,7 @@ else
     cd empty
 
     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
 
     # Disable coverage on 3.8 until we run 3.8 on Windows CI too

ci/rtd-requirements.txt → docs-requirements.txt

@@ -2,13 +2,13 @@
 # This file is autogenerated by pip-compile
 # To update, run:
 #
-#    pip-compile --output-file ci/rtd-requirements.txt ci/rtd-requirements.in
+#    pip-compile --output-file docs-requirements.txt docs-requirements.in
 #
 alabaster==0.7.12         # via sphinx
 async-generator==1.10
 attrs==19.1.0
 babel==2.6.0              # via sphinx
-certifi==2018.11.29       # via requests
+certifi==2019.3.9         # via requests
 chardet==3.0.4            # via requests
 click==7.0                # via towncrier
 contextvars==2.3 ; python_version < "3.7"
@@ -17,22 +17,27 @@ idna==2.8
 imagesize==1.1.0          # via sphinx
 immutables==0.6           # via contextvars
 incremental==17.5.0       # via towncrier
-jinja2==2.10              # via sphinx, towncrier
+jinja2==2.10.1            # via sphinx, towncrier
 markupsafe==1.1.1         # via jinja2
 outcome==1.0.0
 packaging==19.0           # via sphinx
 pygments==2.3.1           # via sphinx
-pyparsing==2.3.1          # via packaging
-pytz==2018.9              # via babel
+pyparsing==2.4.0          # via packaging
+pytz==2019.1              # via babel
 requests==2.21.0          # via sphinx
-six==1.12.0               # via packaging, sphinx
-sniffio==1.0.0
+six==1.12.0               # via packaging
+sniffio==1.1.0
 snowballstemmer==1.2.1    # via sphinx
 sortedcontainers==2.1.0
 sphinx-rtd-theme==0.4.3
-sphinx==1.8.4
+sphinx==2.0.1
+sphinxcontrib-applehelp==1.0.1  # via sphinx
+sphinxcontrib-devhelp==1.0.1  # via sphinx
+sphinxcontrib-htmlhelp==1.0.2  # via sphinx
+sphinxcontrib-jsmath==1.0.1  # via sphinx
+sphinxcontrib-qthelp==1.0.2  # via sphinx
+sphinxcontrib-serializinghtml==1.1.3  # via sphinx
 sphinxcontrib-trio==1.0.2
-sphinxcontrib-websupport==1.1.0  # via sphinx
 toml==0.10.0              # via towncrier
 towncrier==19.2.0
-urllib3==1.24.1           # via requests
+urllib3==1.24.2           # via requests

docs/source/conf.py

@@ -36,6 +36,7 @@
     # trio.abc is documented at random places scattered throughout the docs
     ("py:mod", "trio.abc"),
     ("py:class", "math.inf"),
+    ("py:exc", "Anything else"),
 ]
 autodoc_inherit_docstrings = False
 

docs/source/contributing.rst

@@ -368,6 +368,19 @@ a dangling reference, you can add it to the `nitpick_ignore
 <http://www.sphinx-doc.org/en/stable/config.html#confval-nitpick_ignore>`__
 whitelist in ``docs/source/conf.py``.
 
+To build the docs locally, use our handy ``docs-requirements.txt``
+file to install all of the required packages (possibly using a
+virtualenv). After that, build the docs using ``make html`` in the
+docs directory. The whole process might look something like this::
+
+    cd path/to/project/checkout/
+    pip install -r docs-requirements.txt
+    cd docs
+    make html
+
+You can then browse the docs using Python's builtin http server:
+``python -m http.server 8000 --bind 127.0.0.1 --directory build/html``
+and then opening ``http://127.0.0.1:8000/`` in your web browser.
 
 .. _joining-the-team:
 

docs/source/reference-core.rst

@@ -514,11 +514,6 @@ objects.
       exception, and (2) this scope is the one that was responsible
       for triggering this :exc:`~trio.Cancelled` exception.
 
-      If the same :class:`CancelScope` is reused for multiple ``with``
-      blocks, the :attr:`cancelled_caught` attribute applies to the
-      most recent ``with`` block. (It is reset to :data:`False` each
-      time a new ``with`` block is entered.)
-
    .. autoattribute:: cancel_called
 
 
@@ -640,6 +635,18 @@ Since all tasks are descendents of the initial task, one consequence
 of this is that :func:`run` can't finish until all tasks have
 finished.
 
+.. note::
+
+   A return statement will not cancel the nursery if it still has tasks running::
+
+     async def main():
+         async with trio.open_nursery() as nursery:
+             nursery.start_soon(trio.sleep, 5)
+             return
+
+     trio.run(main)
+
+   This code will wait 5 seconds (for the child task to finish), and then return.
 
 Child tasks and cancellation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1260,7 +1267,7 @@ exit its ``async for`` loop. Then the program shuts down because both
 tasks have exited.
 
 We also added an ``async with`` to the consumer. This isn't as
-important, but can it help us catch mistakes or other problems. For
+important, but it can help us catch mistakes or other problems. For
 example, suppose that the consumer exited early for some reason –
 maybe because of a bug. Then the producer would be sending messages
 into the void, and might get stuck indefinitely. But, if the consumer

docs/source/reference-io.rst

@@ -412,6 +412,7 @@ Socket objects
    arguments require pre-resolved addresses:
 
    * :meth:`~socket.socket.accept`
+   * :meth:`~socket.socket.bind`
    * :meth:`~socket.socket.recv`
    * :meth:`~socket.socket.recv_into`
    * :meth:`~socket.socket.recvfrom`

newsfragments/1005.bugfix.rst

@@ -0,0 +1,8 @@
+An exception encapsulated within a :class:`MultiError` doesn't need to be
+hashable anymore.
+
+.. note::
+
+   This is only supported if you are running python >= 3.6.4. You can
+   refer to `this github PR <https://github.com/python/cpython/pull/4014>`_
+   for details.

newsfragments/1017.doc.rst

@@ -0,0 +1 @@
+To help any user reading through Trio's function implementations, start using public names (not _core) whenever possible.  

newsfragments/917.bugfix.rst

@@ -0,0 +1,3 @@
+The :class:`trio.Path` methods :meth:`~trio.Path.glob` and
+:meth:`~trio.Path.rglob` now return iterables of :class:`trio.Path`
+(not :class:`pathlib.Path`).

newsfragments/960.bugfix.rst

@@ -0,0 +1,4 @@
+The :class:`trio.Path` classmethods, :meth:`~trio.Path.home` and
+:meth:`~trio.Path.cwd`, are now async functions.  Previously, a bug
+in the forwarding logic meant :meth:`~trio.Path.cwd` was synchronous
+and :meth:`~trio.Path.home` didn't work at all.

notes-to-self/how-does-windows-so-reuseaddr-work.py

@@ -0,0 +1,61 @@
+# There are some tables here:
+#   https://web.archive.org/web/20120206195747/https://msdn.microsoft.com/en-us/library/windows/desktop/ms740621(v=vs.85).aspx
+# They appear to be wrong.
+#
+# See https://github.com/python-trio/trio/issues/928 for details and context
+
+import socket
+import errno
+
+modes = ["default", "SO_REUSEADDR", "SO_EXCLUSIVEADDRUSE"]
+bind_types = ["wildcard", "specific"]
+
+def sock(mode):
+    s = socket.socket(family=socket.AF_INET)
+    if mode == "SO_REUSEADDR":
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    elif mode == "SO_EXCLUSIVEADDRUSE":
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+    return s
+
+def bind(sock, bind_type):
+    if bind_type == "wildcard":
+        sock.bind(("0.0.0.0", 12345))
+    elif bind_type == "specific":
+        sock.bind(("127.0.0.1", 12345))
+    else:
+        assert False
+
+def table_entry(mode1, bind_type1, mode2, bind_type2):
+    with sock(mode1) as sock1:
+        bind(sock1, bind_type1)
+        try:
+            with sock(mode2) as sock2:
+                bind(sock2, bind_type2)
+        except OSError as exc:
+            if exc.winerror == errno.WSAEADDRINUSE:
+                return "INUSE"
+            elif exc.winerror == errno.WSAEACCES:
+                return "ACCESS"
+            raise
+        else:
+            return "Success"
+
+print("""
+                                                       second bind
+                               | default           | SO_REUSEADDR      | SO_EXCLUSIVEADDRUSE
+                               | specific| wildcard| specific| wildcard| specific| wildcard
+first bind                     ------------------------------------------------------------"""
+#           default | wildcard |   INUSE | Success |  ACCESS | Success |   INUSE | Success
+)
+
+for i, mode1 in enumerate(modes):
+    for j, bind_type1 in enumerate(bind_types):
+        row = []
+        for k, mode2 in enumerate(modes):
+            for l, bind_type2 in enumerate(bind_types):
+                entry = table_entry(mode1, bind_type1, mode2, bind_type2)
+                row.append(entry)
+                #print(mode1, bind_type1, mode2, bind_type2, entry)
+        print("%19s | %8s | " % (mode1, bind_type1)
+              + " | ".join(["%7s" % entry for entry in row]))

notes-to-self/print-task-tree.py

@@ -1,3 +1,7 @@
+# NOTE:
+# possibly it would be easier to use https://pypi.org/project/tree-format/
+# instead of formatting by hand like this code does...
+
 """
 Demo/exploration of how to print a task tree. Outputs:
 

setup.cfg

@@ -0,0 +1,2 @@
+[tool:pytest]
+xfail_strict = true

test-requirements.in

@@ -9,7 +9,7 @@ pylint         # for pylint finding all symbols tests
 jedi           # for jedi code completion tests
 
 # Tools
-yapf ==0.26.0  # formatting
+yapf ==0.27.0  # formatting
 flake8
 
 # https://github.com/python-trio/trio/pull/654#issuecomment-420518745

test-requirements.txt

@@ -5,30 +5,30 @@
 #    pip-compile --output-file test-requirements.txt test-requirements.in
 #
 asn1crypto==0.24.0        # via cryptography
-astroid==2.2.4            # via pylint
+astroid==2.2.5            # via pylint
 async-generator==1.10
 atomicwrites==1.3.0       # via pytest
 attrs==19.1.0
 backcall==0.1.0           # via ipython
-cffi==1.12.2              # via cryptography
+cffi==1.12.3              # via cryptography
 contextvars==2.3 ; python_version < "3.7"
-coverage==4.5.2           # via pytest-cov
+coverage==4.5.3           # via pytest-cov
 cryptography==2.6.1       # via pyopenssl, trustme
-decorator==4.3.2          # via ipython, traitlets
+decorator==4.4.0          # via ipython, traitlets
 entrypoints==0.3          # via flake8
 flake8==3.7.7
 idna==2.8
 immutables==0.6           # via contextvars
 ipython-genutils==0.2.0   # via traitlets
-ipython==7.3.0
-isort==4.3.12             # via pylint
+ipython==7.5.0
+isort==4.3.17             # via pylint
 jedi==0.13.3
 lazy-object-proxy==1.3.1  # via astroid
 mccabe==0.6.1             # via flake8, pylint
-more-itertools==6.0.0     # via pytest
+more-itertools==7.0.0     # via pytest
 outcome==1.0.0
-parso==0.3.4              # via jedi
-pexpect==4.6.0            # via ipython
+parso==0.4.0              # via jedi
+pexpect==4.7.0            # via ipython
 pickleshare==0.7.5        # via ipython
 pluggy==0.9.0             # via pytest
 prompt-toolkit==2.0.9     # via ipython
@@ -42,13 +42,13 @@ pylint==2.3.1
 pyopenssl==19.0.0
 pytest-cov==2.6.1
 pytest-faulthandler==1.5.0
-pytest==4.3.0
+pytest==4.4.1
 six==1.12.0               # via astroid, cryptography, prompt-toolkit, pyopenssl, pytest, traitlets
-sniffio==1.0.0
+sniffio==1.1.0
 sortedcontainers==2.1.0
 traitlets==4.3.2          # via ipython
-trustme==0.5.0
+trustme==0.5.1
 typed-ast==1.3.1 ; python_version < "3.7" and implementation_name == "cpython"
 wcwidth==0.1.7            # via prompt-toolkit
 wrapt==1.11.1             # via astroid
-yapf==0.26.0
+yapf==0.27.0

trio/_abc.py

@@ -1,7 +1,7 @@
 from abc import ABCMeta, abstractmethod
 from typing import Generic, TypeVar
 from ._util import aiter_compat
-from . import _core
+import trio
 
 
 # We use ABCMeta instead of ABC, plus set __slots__=(), so as not to force a
@@ -708,5 +708,5 @@ def __aiter__(self):
     async def __anext__(self):
         try:
             return await self.receive()
-        except _core.EndOfChannel:
+        except trio.EndOfChannel:
             raise StopAsyncIteration