docs: def shutdown_waits_for(coro, loop=None):
      """Prevent coro from being cancelled during the shutdown sequence.
  
      The trick here is that we add this coro to the global
      "DO_NOT_CANCEL" collection, and then later during the shutdown
      sequence we make sure that the task that wraps this coro will NOT
      be cancelled.
  
      To make this work, we have to create a super-secret task, below, that
      communicates with the caller (which "awaits" us) via a Future. Using
      a Future in this way allows us to avoid awaiting the Task, which
      decouples the Task from the normal exception propagation which would
      normally happen when the outer Task gets cancelled.  We get the
      result of coro back to the caller via Future.set_result.
  
      NOTE that during the shutdown sequence, the caller WILL NOT be able
      to receive a result, since the caller will likely have been
      cancelled.  So you should probably not rely on capturing results
      via this function.
      """
      loop = loop or get_event_loop()
      fut = loop.create_future()  # This future will connect coro and the caller.
  
      async def coro_proxy():
          """This function will await coro, but it will also send the result
          over the the future. Remember: the outside caller (of
          shutdown_waits_for) will be awaiting fut, NOT coro(), due to
          the decoupling. However, when coro completes, we need to send its
          result over to the fut to make it look *as if* it was just coro
          running the whole time. This whole thing is a teeny magic trick.
          """
          try:
              result = await coro
          except (CancelledError, Exception) as e:
              set_fut_done = partial(fut.set_exception, e)
          else:
              set_fut_done = partial(fut.set_result, result)
  
          if not fut.cancelled():
              set_fut_done()
  
      new_coro = coro_proxy()  # We'll taskify this one instead of coro.
      _DO_NOT_CANCEL_COROS.add(new_coro)  # The new task must not be cancelled.
      loop.create_task(new_coro)  # Make the task
  
      # Ok, so we *could* simply return fut.  Callers can await it as normal,
      # e.g.
      #
      # async def blah():
      #   x = await shutdown_waits_for(bleh())
      #
      # That will work fine.  However, callers may *also* want to detach the
      # call from the current execution context, e.g.
      #
      # async def blah():
      #   loop.create_task(shutdown_waits_for(bleh()))
      #
      # This will only work if shutdown_waits_for() returns a coroutine.
      # Therefore, we just make a new coroutine to wrap the `await fut` and
      # return that.  Then both things will work.
      #
      # (Side note: instead of callers using create_tasks, it would also work
      # if they used `asyncio.ensure_future()` instead, since that can work
      # with futures. But I don't like ensure_future.)
      #
      # (Another side note: You don't even need `create_task()` or
      # `ensure_future()`...If you don't want a result, you can just call
      # `shutdown_waits_for()` as a flat function call, no await or anything,
      # and it should still work; unfortunately it causes a RuntimeWarning to
      # tell you that ``inner()`` was never awaited :/
  
      async def inner():
          return await fut
  
      return inner()