Add nursery.start and nursery.start_soon

.travis.yml

@@ -11,14 +11,6 @@ dist: trusty
 
 matrix:
   include:
-    - os: linux
-      language: python
-      python: 3.6
-      env: DOC_BUILD=1
-    - os: linux
-      language: python
-      python: 3.6
-      env: FORMATTING=1
     - os: linux
       language: generic
       env: USE_PYPY_NIGHTLY=1
@@ -31,6 +23,14 @@ matrix:
     - os: osx
       language: generic
       env: MACPYTHON=3.6.0
+    - os: linux
+      language: python
+      python: 3.6
+      env: CHECK_DOCS=1
+    - os: linux
+      language: python
+      python: 3.6
+      env: CHECK_FORMATTING=1
 
 script:
   - ci/travis.sh

ci/travis.sh

@@ -35,9 +35,10 @@ if [ "$USE_PYPY_NIGHTLY" = "1" ]; then
     # something like "pypy-c-jit-89963-748aa3022295-linux64"
     PYPY_DIR=$(echo pypy-c-jit-*)
     PYTHON_EXE=$PYPY_DIR/bin/pypy3
-    $PYTHON_EXE -m ensurepip
-    $PYTHON_EXE -m pip install virtualenv
-    $PYTHON_EXE -m virtualenv testenv
+    ($PYTHON_EXE -m ensurepip \
+     && $PYTHON_EXE -m pip install virtualenv \
+     && $PYTHON_EXE -m virtualenv testenv) \
+        || echo "pypy nightly is broken; skipping tests"; exit 0
     source testenv/bin/activate
 fi
 
@@ -55,36 +56,37 @@ fi
 
 pip install -U pip setuptools wheel
 
-python setup.py sdist --formats=zip
-pip install dist/*.zip
-
-if [ "$DOC_BUILD" = "1" ]; then
-    pip install -Ur ci/rtd-requirements.txt
-    cd docs
-    # -n (nit-picky): warn on missing references
-    # -W: turn warnings into errors
-    sphinx-build -nW  -b html source build
-elif [ "$FORMATTING" = "1" ]; then
+if [ "$CHECK_FORMATTING" = "1" ]; then
     pip install -U yapf
-    yapf -rdp setup.py trio > formatting-fixes.patch
-    if [ -s formatting-fixes.patch ]; then
+    if ! yapf -rpd setup.py trio; then
         cat <<EOF
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-The following formatting problems were found. To fix them, run
+Formatting problems were found (listed above). To fix them, run
 
-   pip install yapf
-   yapf -rip setup.py trio
+   pip install -U yapf
+   yapf -rpi setup.py trio
 
 in your local checkout.
 
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 EOF
-        cat formatting-fixes.patch
         exit 1
     fi
+    exit 0
+fi
+
+python setup.py sdist --formats=zip
+pip install dist/*.zip
+
+if [ "$CHECK_DOCS" = "1" ]; then
+    pip install -Ur ci/rtd-requirements.txt
+    cd docs
+    # -n (nit-picky): warn on missing references
+    # -W: turn warnings into errors
+    sphinx-build -nW  -b html source build
 else
     # Actual tests
     pip install -Ur test-requirements.txt

docs/source/reference-core.rst

@@ -916,6 +916,51 @@ Nursery objects provide the following interface:
                             (i.e. its ``async with`` block has
                             exited).
 
+   .. method:: start_soon(async_fn, *args, name=None)
+
+      Like :meth:`spawn`, but doesn't return the newly created task.
+
+   .. method:: start(async_fn, *args, name=None)
+      :async:
+
+      Like :meth:`start`, but blocks until the new task has finished
+      initializing itself, and optionally returns some information
+      from it.
+
+      The ``async_fn`` must accept a ``task_status`` keyword argument,
+      and it must make sure that it (or someone) eventually calls
+      ``task_status.started()``.
+
+      The conventional way to define ``async_fn`` is like::
+
+         async def async_fn(arg1, arg2, *, task_status=trio.STATUS_IGNORED):
+             ...
+             task_status.started()
+             ...
+
+      :attr:`trio.STATUS_IGNORED` is a special global object with a
+      do-nothing ``started`` method. This way your function supports
+      being called either like ``await nursery.start(async_fn, arg1,
+      arg2)`` or directly like ``await async_fn(arg1, arg2)``, and
+      either way it can call ``task_status.started()`` without
+      worrying about which mode it's in. Defining your function like
+      this will make it obvious to readers that it supports being used
+      in both modes.
+
+      Before the child calls ``task_status.started()``, it's
+      effectively run underneath the call to :meth:`start`: if it
+      raises an exception then that exception is reported by
+      :meth:`start`, and does *not* propagate out of the nursery. If
+      :meth:`start` is cancelled, then the child task is also
+      cancelled.
+
+      When the child calls ``task_status.started()``, it's moved from
+      out from underneath :meth:`start` and into the given nursery.
+
+      If the child task passes a value to
+      ``task_status.started(value)``, then :meth:`start` returns this
+      value. Otherwise it returns ``None``.
+
    .. attribute:: cancel_scope
 
       Creating a nursery also implicitly creates a cancellation scope,
@@ -933,6 +978,9 @@ Nursery objects provide the following interface:
       A :class:`~trio.UnboundedQueue` which receives each child
       :class:`~trio.Task` object when it exits.
 
+      It also receives a ``None`` value after each call to
+      :meth:`start`.
+
    .. attribute:: children
 
       A :class:`frozenset` containing all the child
@@ -968,6 +1016,10 @@ Nursery objects provide the following interface:
          nursery.reap(task)
          return task.result.unwrap()
 
+.. attribute:: STATUS_IGNORED
+
+   See :meth:`~The nursery interface.start`.
+
 
 Task object API
 +++++++++++++++