process = await nursery.start(run_process, ...)

docs/source/reference-io.rst

@@ -664,22 +664,43 @@ Spawning subprocesses
 
 Trio provides support for spawning other programs as subprocesses,
 communicating with them via pipes, sending them signals, and waiting
-for them to exit. The interface for doing so consists of two layers:
+for them to exit.
 
-* :func:`trio.run_process` runs a process from start to
-  finish and returns a :class:`~subprocess.CompletedProcess` object describing
-  its outputs and return value. This is what you should reach for if you
-  want to run a process to completion before continuing, while possibly
-  sending it some input or capturing its output. It is modelled after
-  the standard :func:`subprocess.run` with some additional features
-  and safer defaults.
+Most of the time, this is done through our high-level interface,
+`trio.run_process`. It lets you either run a process to completion
+while optionally capturing the output, or else run it in a background
+task and interact with it while it's running:
 
-* `trio.open_process` starts a process in the background and returns a
-  `Process` object to let you interact with it. Using it requires a
-  bit more code than `run_process`, but exposes additional
-  capabilities: back-and-forth communication, processing output as
-  soon as it is generated, and so forth. It is modelled after the
-  standard library :class:`subprocess.Popen`.
+.. autofunction:: trio.run_process
+
+.. autoclass:: trio.Process
+
+   .. autoattribute:: returncode
+
+   .. automethod:: wait
+
+   .. automethod:: poll
+
+   .. automethod:: kill
+
+   .. automethod:: terminate
+
+   .. automethod:: send_signal
+
+   .. note:: :meth:`~subprocess.Popen.communicate` is not provided as a
+      method on :class:`~trio.Process` objects; call :func:`~trio.run_process`
+      normally for simple capturing, or write the loop yourself if you
+      have unusual needs. :meth:`~subprocess.Popen.communicate` has
+      quite unusual cancellation behavior in the standard library (on
+      some platforms it spawns a background thread which continues to
+      read from the child process even after the timeout has expired)
+      and we wanted to provide an interface with fewer surprises.
+
+If `trio.run_process` is too limiting, we also offer a low-level API,
+`trio.open_process`. For example, use `open_process` if you want to
+spawn a child process that outlives the parent process:
+
+.. autofunction:: trio.open_process
 
 
 .. _subprocess-options:
@@ -705,58 +726,6 @@ with a process, so it does not support the ``encoding``, ``errors``,
 options.
 
 
-Running a process and waiting for it to finish
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The basic interface for running a subprocess start-to-finish is
-:func:`trio.run_process`.  It always waits for the subprocess to exit
-before returning, so there's no need to worry about leaving a process
-running by mistake after you've gone on to do other things.
-:func:`~trio.run_process` is similar to the standard library
-:func:`subprocess.run` function, but tries to have safer defaults:
-with no options, the subprocess's input is empty rather than coming
-from the user's terminal, and a failure in the subprocess will be
-propagated as a :exc:`subprocess.CalledProcessError` exception. Of
-course, these defaults can be changed where necessary.
-
-.. autofunction:: trio.run_process
-
-
-Interacting with a process as it runs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you want more control than :func:`~trio.run_process` affords, you
-can use `trio.open_process` to spawn a subprocess, and then interact
-with it using the `Process` interface.
-
-.. autofunction:: trio.open_process
-
-.. autoclass:: trio.Process
-
-   .. autoattribute:: returncode
-
-   .. automethod:: aclose
-
-   .. automethod:: wait
-
-   .. automethod:: poll
-
-   .. automethod:: kill
-
-   .. automethod:: terminate
-
-   .. automethod:: send_signal
-
-   .. note:: :meth:`~subprocess.Popen.communicate` is not provided as a
-      method on :class:`~trio.Process` objects; use :func:`~trio.run_process`
-      instead, or write the loop yourself if you have unusual
-      needs. :meth:`~subprocess.Popen.communicate` has quite unusual
-      cancellation behavior in the standard library (on some platforms it
-      spawns a background thread which continues to read from the child
-      process even after the timeout has expired) and we wanted to
-      provide an interface with fewer surprises.
-
-
 .. _subprocess-quoting:
 
 Quoting: more than you wanted to know

newsfragments/1104.removal.rst

@@ -0,0 +1,4 @@
+The ``aclose`` method on `Process` has been deprecated, and ``async
+with process_obj`` has also been deprecated. We recommend switching to
+the new ``nursery.start(trio.run_process, ...)`` API instead, which is
+more powerful and predictable.