Add basic docs

Author: 1st1

Doc/library/asyncio-future.rst

@@ -65,7 +65,7 @@ Future Functions
       and *loop* is not specified and there is no running event loop.
 
 
-.. function:: wrap_future(future, *, loop=None)
+.. function:: wrap_future(future, /, *, loop=None)
 
    Wrap a :class:`concurrent.futures.Future` object in a
    :class:`asyncio.Future` object.

Doc/library/asyncio-stack.rst

@@ -0,0 +1,80 @@
+.. currentmodule:: asyncio
+
+
+.. _asyncio-stack:
+
+===================
+Stack Introspection
+===================
+
+**Source code:** :source:`Lib/asyncio/stack.py`
+
+-------------------------------------
+
+asyncio has powerful runtime call stack introspection utilities
+to trace the entire call graph of a running coroutine or task, or
+a suspended *future*.
+
+.. versionadded:: 3.14
+
+
+.. function:: capture_call_stack(*, future=None)
+
+   Capture the async call stack for the current task or the provided
+   :class:`Task` or :class:`Future`.
+
+   The function receives an optional keyword-only *future* argument.
+   If not passed, the current task will be used. If there's no current task,
+   the function returns ``None``.
+
+   Returns a ``FutureCallStack`` named tuple:
+
+   * ``FutureCallStack(future, call_stack, awaited_by)``
+
+      Where 'future' is a reference to a *Future* or a *Task*
+      (or their subclasses.)
+
+      ``call_stack`` is a list of ``FrameCallStackEntry`` and
+      ``CoroutineCallStackEntry`` objects (more on them below.)
+
+      ``awaited_by`` is a list of ``FutureCallStack`` tuples.
+
+   * ``FrameCallStackEntry(frame)``
+
+      Where ``frame`` is a frame object of a regular Python function
+      in the call stack.
+
+   * ``CoroutineCallStackEntry(coroutine)``
+
+      Where ``coroutine`` is a coroutine object of an awaiting coroutine
+      or asyncronous generator.
+
+
+Low level utility functions
+===========================
+
+To introspect an async call stack asyncio requires cooperation from
+control flow structures, such as :func:`shield` or :class:`TaskGroup`.
+Any time an intermediate ``Future`` object with low-level APIs like
+:meth:`Future.add_done_callback() <asyncio.Future.add_done_callback>` is
+involved, the following two functions should be used to inform *asyncio*
+about how exactly such intermediate future objects are connected with
+the tasks they wrap or control.
+
+
+.. function:: future_add_to_awaited_by(future, waiter, /)
+
+   Record that *future* is awaited on by *waiter*.
+
+   Both *future* and *waiter* must be instances of
+   :class:`asyncio.Future <Future>` or :class:`asyncio.Task <Task>` or
+   their subclasses, otherwise the call would have no effect.
+
+
+.. function:: future_discard_from_awaited_by(future, waiter, /)
+
+   Record that *future* is no longer awaited on by *waiter*.
+
+   Both *future* and *waiter* must be instances of
+   :class:`asyncio.Future <Future>` or :class:`asyncio.Task <Task>` or
+   their subclasses, otherwise the call would have no effect.

Doc/library/asyncio.rst

@@ -99,6 +99,7 @@ You can experiment with an ``asyncio`` concurrent context in the :term:`REPL`:
    asyncio-subprocess.rst
    asyncio-queue.rst
    asyncio-exceptions.rst
+   asyncio-stack.rst
 
 .. toctree::
    :caption: Low-level APIs

Lib/asyncio/futures.py

@@ -423,7 +423,7 @@ def wrap_future(future, *, loop=None):
     return new_future
 
 
-def future_add_to_awaited_by(fut, waiter):
+def future_add_to_awaited_by(fut, waiter, /):
     """Record that `fut` is awaited on by `waiter`."""
     # For the sake of keeping the implementation minimal and assuming
     # that 99.9% of asyncio users use the built-in Futures and Tasks
@@ -451,7 +451,7 @@ def future_add_to_awaited_by(fut, waiter):
         fut._asyncio_awaited_by.add(waiter)
 
 
-def future_discard_from_awaited_by(fut, waiter):
+def future_discard_from_awaited_by(fut, waiter, /):
     """Record that `fut` is no longer awaited on by `waiter`."""
     # See the comment in "future_add_to_awaited_by()" body for
     # details on implemntation.

Lib/asyncio/stack.py

@@ -4,6 +4,7 @@
 import types
 import typing
 
+from . import events
 from . import futures
 from . import tasks
 
@@ -103,11 +104,20 @@ def capture_call_stack(*, future: any = None) -> FutureCallStack | None:
     returns None.
     """
 
+    loop = events._get_running_loop()
+
     if future is not None:
-        if future is not tasks.current_task():
+        # Check if we're in a context of a running event loop;
+        # if yes - check if the passed future is the currently
+        # running task or not.
+        if loop is None or future is not tasks.current_task():
             return _build_stack_for_future(future)
         # else: future is the current task, move on.
     else:
+        if loop is None:
+            raise RuntimeError(
+                'capture_call_stack() is called outside of a running '
+                'event loop and no *future* to introspect was provided')
         future = tasks.current_task()
 
     if future is None:

Modules/_asynciomodule.c

@@ -3839,6 +3839,7 @@ _asyncio.future_add_to_awaited_by
 
     fut: object
     waiter: object
+    /
 
 Record that `fut` is awaited on by `waiter`.
 
@@ -3847,7 +3848,7 @@ Record that `fut` is awaited on by `waiter`.
 static PyObject *
 _asyncio_future_add_to_awaited_by_impl(PyObject *module, PyObject *fut,
                                        PyObject *waiter)
-/*[clinic end generated code: output=0ab9a1a63389e4df input=29259cdbafe9e7bf]*/
+/*[clinic end generated code: output=0ab9a1a63389e4df input=06e6eaac51f532b9]*/
 {
     asyncio_state *state = get_asyncio_state(module);
     if (future_awaited_by_add(state, fut, waiter)) {
@@ -3861,6 +3862,7 @@ _asyncio.future_discard_from_awaited_by
 
     fut: object
     waiter: object
+    /
 
 Record that `fut` is no longer awaited on by `waiter`.
 
@@ -3869,7 +3871,7 @@ Record that `fut` is no longer awaited on by `waiter`.
 static PyObject *
 _asyncio_future_discard_from_awaited_by_impl(PyObject *module, PyObject *fut,
                                              PyObject *waiter)
-/*[clinic end generated code: output=a03b0b4323b779de input=5d67a3edc79b6094]*/
+/*[clinic end generated code: output=a03b0b4323b779de input=b5f7a39ccd36b5db]*/
 {
     asyncio_state *state = get_asyncio_state(module);
     if (future_awaited_by_discard(state, fut, waiter)) {