asyncify-codemod

asyncify-codemod is a codemod that converts synchronous Python code into async where possible. It focuses on a few common patterns (like requests, time.sleep, and file I/O) and rewrites them to async equivalents.

Usage

Run with pipx

pipx run asyncify-codemod [files you wish to transform ...]

E.g. if your python source files are located in src/:

pipx run asyncify-codemod src/**/*.py

pipx run asyncify-codemod --stdout path/to/file.py path/to/another.py

Comparison: asyncio.to_thread() vs async rewrites

Because “real async I/O” and “sync I/O in a thread” solve different problems, and they behave very differently at scale and under cancellation.

Where to_thread is great

Fast migration / compatibility shim: you can call existing blocking code from an async app without freezing the event loop. No behavioral rewrite: minimal code churn; good for legacy code you don’t want to touch yet. Sync-only dependencies: if there is no solid async alternative, threads are the pragmatic choice.

Where to_thread breaks down (and why a codemod helps)

• Concurrency limits: to_thread is bounded by a thread pool. You can run thousands of concurrent await httpx/... calls; you generally can’t run thousands of threads. Under load, this becomes queueing/latency rather than throughput.
• Cancellation semantics: cancelling an await to_thread(...) usually does not stop the underlying blocking call; it just stops waiting for it. With real async libs, cancellation is often propagated more cleanly (still not perfect everywhere, but materially better).
• Resource efficiency: threads cost memory + scheduling overhead; async sockets/file ops can be much lighter per in-flight operation. You can’t “mix in” async behavior inside: if a function is wrapped, everything inside it stays sync. A codemod can turn the internals into await points (time.sleep → anyio.sleep, requests → httpx, open() → anyio.open_file), enabling cooperative scheduling throughout the call graph.
• Observability/context: thread offloading can complicate tracing/log context propagation and debugging (it’s doable, just another layer). Pure async tends to integrate more directly with async frameworks’ middleware/instrumentation.

Use a codemod when you want the codebase to become natively async so it scales better, cancels better, and composes naturally with async frameworks—without hand-editing hundreds of mechanical changes.

Caveats

Sync-only dependencies

Currently, this codemod only rewrites commonly used I/O-bound operations with async alternatives (as mentioned above). If you're using custom libraries where there are no solid async alternatives, they will in your new async functions after a codemod. This is a huge performance blocker and the only way to resolve this right now is to manually update its usages (i.e. send it to asyncio.to_thread).