Feature Design Discussion: Blocking Analysis

[jhance]

We would like to facilitate a migration from a large (formerly python 2 codebase) synchronous codebase to asyncio. Our codebase will forever probably contain a mixture of asyncio and synchronous code.

However, asyncio can be crippled if someone accidentally adds something like a time.sleep that blocks the event loop, or any synchronous network operation - or even a subprocess.run. In order to combat this, we are banning the function time.sleep and replacing it with something like this:

def blocking_sleep(t: float) -> None:
    assert_no_running_loop()
    time.sleep(t)

This covers the runtime case - instead of blocking at runtime we will raise an exception. This means our tests are likely to catch such issues. But not all of our code has tests. We would like to catch issues in mypy as well. One could imagine it is fairly simple to use either a mypy plugin or similar analysis tool to prevent things like this:

async def foo() -> None:
    blocking_sleep(10)

But the call to blocking_sleep may not be directly within the function foo and we still want to catch this.

One solution would be to make a monad-like construct Blocking like this:

from mypy_extensions import Blocking

def blocking_sleep(t: float) -> Blocking[None]:
    assert_no_running_loop()
    time.sleep(t)

The semantics would be simple - a call to a blocking callable would error if it is not itself within a blocking function. The only way to call it from outside a blocking function would be to use something like asyncio.to_thread or some utiltiy like allow_unsafe_blocking_call().

It would probably be feasible to annotate only a few function e.g. blocking_sleep and write a tool that automatically propagates all of the Blocking annotations and rewrites the code. This would work. The main problem is that the Blocking annotations may be annoying to developers/cause developer friction until more codebase is async.

The upside to this approach is that it facilites a migration to asyncio through a relatively simple substitution, blocking functions become async and calls to blocking functions get an await. One might note that this is mostly because annotating the blocking-ness is essentially isomorphic to annotating async-ness, but annotating the blocking-ness is much safer than a bulk conversion to asyncio becuase it won't have any runtime effect.

A second solution would be for a new mypy pass that, given a few root functions like blocking_sleep and other known blocking functions, automatically propagates the blocking-ness throughout and raises errors on invalid callsites. This has the advantage that we don't have to annotate everything. The disadvantages are that you can't tell if a function is blocking from reading it (although mypy could perhaps expose a query interface to ask it). Error generation may also be more difficult because we will need to produce some sort of callstack at which a function could block. We may need some way to be able to tell it that it is wrong, e.g. annotate a function as explicitly NotBlocking or similar.

I believe some sort of this feature will be required for asyncio to work on our large codebase. To make it will integrated with builtins and typeshed we would need a PEP, but I think it is fine for us to discuss here what the ideal state would be (internally we may use a mypy plugin or similar to rewrite typeshed stuff that should be blocking) without worrying about things like whether a PEP is necessary.

[jhance]

Jukka's comments pasted here:

about the “blockingness”: this could be property of a callable. annotating it using Block[int] seems like a good approach. propagating blocking information during semantic analysis or type checking may be feasible, if we are happy with a rough approximation. full blockingness analysis may be too expensive to compute on every mypy run.

an alternative would be to implement a batch annotator that infer blockingness information and adds to all blocking functions. since this would only need to be run once/every once in a while, the performance wouldn’t matter. this likely wouldn’t get things 100% correct — we’d need some manual updates afterwards, or at least # type: ignores.

we’d first need to annotate (at least important) library functions that may block, some of which are in stdlib. we could maintain a list of stdlib functions that block separately and apply the blocking return type to the signatures in stdlib stubs. we probably won’t be able to modify the stubs, since the stubs are shared between multiple tools — unless we write a PEP about this feature and get it accepted.

one worry with this approach i have is that a huge amount of existing [internal term] code would get Block[...] return types, and this would add friction to development. automatic inference, even if not very precise, may thus be a better option.

actually inference would have to run during/after type checking, so that we can resolve method calls. it could be a lightweight pass after type checking where we propagate a “blocking” flag to every function from a set of source with Block[...] return type annotations, and check that no async functions call a function with a blocking flag.

there will be various additional details to figure out if we want to make the coverage useful (e.g. dealing with inheritance, variables with annotated callable types, properties, etc.). but the inference-based approach seems feasible to me, at maybe 1-3% perf overhead to mypy runs.

when we generate errors, we might want to print out a trace of inferred blocking functions starting from an explicit Blocking[...] annotation to make it easier for users to understand why some function is blocking.

[jhance]

One issue I see with inference is something like

class A(Protocol):
   @abc.abstractmethod
   def foo() -> None:
      pass
      
def bar(a: A) -> None:
     a.foo() # does it block?

We could maybe require abstract classes to be explicit about it.

[tasercake]

I'd be interested in contributing here as I also work with a large codebase with a mix of sync/async code.

Perhaps someone more familiar with mypy internals could answer this – would it be feasible to start with a mypy plugin with hard-coded knowledge of some common blocking functions such as the various networking libraries out there?

ruff takes a similar approach by flagging calls to known blocking functions in async contexts, but it's limited in that it can't perform cross-file analysis.