pyforjs | Python 3.14+ for JavaScript engineers

Node's event loop is always running; Python's is not. Lazy coroutines, explicit scheduling, and the GIL's effect on which concurrency primitive you actually want.

The syntax is nearly identical. async def, await, the same shape of code. The runtime model is not, and that is where the bugs come from.

Nothing runs until you start a loop

Node boots an event loop before your first line executes. Python has none until you ask for one, and a coroutine that is never awaited never runs at all.

entry.ts

const p = fetchUser(); // already running

async function main() {

return await p;

}

main();

entry.py

Starting Python…

import asyncio
async def fetch_user():
    return "ada"
coro = fetch_user()      # nothing has happened yet
async def main():
    return await coro
print(asyncio.run(main()))

The silent no-op

Calling an async def and discarding the result does nothing, no request, no error, just a RuntimeWarning: coroutine was never awaited if you are lucky. In JavaScript the equivalent fires the request and swallows the rejection. Both are bugs; Python's is quieter at runtime and louder at review time.

Eager Promises, lazy coroutines

	JavaScript Promise	Python coroutine
Starts executing	on construction	on `await`, or when wrapped in a task
Awaiting twice	returns the cached result	`RuntimeError: cannot reuse already awaited`
Fire and forget	`void p`	`asyncio.create_task(coro)`

To get Promise-like eagerness, schedule the coroutine explicitly:

scheduling.py

Starting Python…

import asyncio
import time
async def work(name, seconds):
    await asyncio.sleep(seconds)
    return name
async def sequential():
    start = time.time()
    a = await work("a", 0.2)
    b = await work("b", 0.2)
    return a, b, round(time.time() - start, 1)
async def concurrent():
    start = time.time()
    ta = asyncio.create_task(work("a", 0.2))   # starts now
    tb = asyncio.create_task(work("b", 0.2))
    a, b = await ta, await tb
    return a, b, round(time.time() - start, 1)
print("sequential:", asyncio.run(sequential()))
print("concurrent:", asyncio.run(concurrent()))

Combinators

JavaScript	Python	Behaviour
`Promise.all([p1, p2])`	`asyncio.gather(t1, t2)`	concurrent; raises on the first failure
`Promise.allSettled([...])`	`asyncio.gather(..., return_exceptions=True)`	collects results and exceptions
`Promise.race([...])`	`asyncio.wait(..., return_when=FIRST_COMPLETED)`	returns when the first finishes
`AbortSignal.timeout(ms)`	`async with asyncio.timeout(s)`	3.11+, raises `TimeoutError`

combinators.py

Starting Python…

import asyncio
async def ok(n):
    await asyncio.sleep(0.05)
    return n
async def boom():
    await asyncio.sleep(0.05)
    raise ValueError("failed")
async def main():
    settled = await asyncio.gather(ok(1), boom(), ok(3), return_exceptions=True)
    print("allSettled equivalent:", settled)
    try:
        await asyncio.gather(ok(1), boom())
    except ValueError as e:
        print("gather without return_exceptions raises:", e)
    try:
        async with asyncio.timeout(0.01):
            await ok(1)
    except TimeoutError:
        print("timed out, as expected")
asyncio.run(main())

Structured concurrency with TaskGroup

Promise.all fails fast but abandons its siblings, they keep running, their results discarded, and nothing awaits them again. Python 3.11+ has a stronger contract. It is called structured concurrency. An asyncio.TaskGroup scope does not exit until every task started inside it is finished, or cancelled, if one of them failed first.

task_groups.py

Starting Python…

import asyncio
async def fetch(name: str, seconds: float) -> str:
    await asyncio.sleep(seconds)
    return name
async def boom() -> None:
    await asyncio.sleep(0.01)
    raise ValueError("failed")
# Happy path: the block does not exit until every task is done.
async def all_good():
    async with asyncio.TaskGroup() as tg:
        t1 = tg.create_task(fetch("a", 0.05))
        t2 = tg.create_task(fetch("b", 0.02))
    # past this line, both tasks are finished — no dangling work
    return t1.result(), t2.result()
print("all good:", asyncio.run(all_good()))
# Failure path: boom() raises, the slow sibling is cancelled,
# and both errors surface together in an ExceptionGroup.
async def with_failure():
    try:
        async with asyncio.TaskGroup() as tg:
            slow = tg.create_task(fetch("slow", 5.0))
            tg.create_task(boom())
    except* ValueError as eg:
        outcome = f"caught {[str(e) for e in eg.exceptions]}, sibling cancelled={slow.cancelled()}"
    return outcome
print(asyncio.run(with_failure()))

import asyncio

async def fetch(name: str, seconds: float) -> str:
    await asyncio.sleep(seconds)
    return name

async def boom() -> None:
    await asyncio.sleep(0.01)
    raise ValueError("failed")

# Happy path: the block does not exit until every task is done.
async def all_good():
    async with asyncio.TaskGroup() as tg:
        t1 = tg.create_task(fetch("a", 0.05))
        t2 = tg.create_task(fetch("b", 0.02))
    # past this line, both tasks are finished — no dangling work
    return t1.result(), t2.result()

print("all good:", asyncio.run(all_good()))

# Failure path: boom() raises, the slow sibling is cancelled,
# and both errors surface together in an ExceptionGroup.
async def with_failure():
    try:
        async with asyncio.TaskGroup() as tg:
            slow = tg.create_task(fetch("slow", 5.0))
            tg.create_task(boom())
    except* ValueError as eg:
        outcome = f"caught {[str(e) for e in eg.exceptions]}, sibling cancelled={slow.cancelled()}"
    return outcome

print(asyncio.run(with_failure()))

	`Promise.all` + `AbortSignal`	`asyncio.TaskGroup`
First failure	rejects; siblings keep running	cancels every sibling, then raises
Error shape	the single first rejection	`ExceptionGroup`, all failures, collected
Cancellation wiring	you thread the signal through by hand	automatic within the scope
After the block	may still have in-flight requests	guaranteed: no task survives the block

except* is a new keyword shape

A TaskGroup failure surfaces as an ExceptionGroup, and you catch it with except*, a separate syntax that unwraps the group and matches each member exception type independently. Plain except ValueError will not catch it, because a group of ValueErrors is not itself a ValueError. Also note return is illegal inside an except* block, assign a result and return after, as the snippet does.

The rule of thumb is this. Use gather for quick fan-outs where abandonment is fine (or where you asked for return_exceptions=True), TaskGroup whenever sibling tasks share a lifetime, which is most request handlers.

The GIL

CPython holds a global lock around bytecode execution, so threads do not give you CPU parallelism. They do give you concurrency during blocking I/O, because the lock is released while waiting.

Workload	Reach for	Why
Network / disk I/O	`asyncio`	thousands of waits, one thread, no lock contention
Blocking library with no async API	`asyncio.to_thread` / `threading`	the GIL is released during the blocking call
CPU-bound number crunching	`multiprocessing`	separate interpreters, separate GILs
CPU-bound array maths	`numpy`	the heavy loops release the GIL in C

PEP 703 makes the GIL optional. In 3.14 the free-threaded build is supported but still optional, the GIL remains the default, and whether it ever becomes the default build is undecided. It does not change the advice above. Most C extensions still assume the lock exists.

Kata

The pattern you will write in your first week on any Python service. Fan out, but not too far.

Kata

Fetch all ten endpoints concurrently while never having more than three requests in flight. Use asyncio.Semaphore to enforce the limit and asyncio.gather to run them. Results must come back in the original order.

kata_03.py

Starting Python…

import asyncio
in_flight = 0
peak = 0
async def fetch(url: str) -> str:
    """Simulated request. Do not modify — it records concurrency for the tests."""
    global in_flight, peak
    in_flight += 1
    peak = max(peak, in_flight)
    try:
        await asyncio.sleep(0.02)
        return f"body of {url}"
    finally:
        in_flight -= 1
async def fetch_all(urls: list[str], limit: int = 3) -> list[str]:
    # TODO: run these concurrently, at most `limit` at a time, order preserved.
    return [await fetch(url) for url in urls]
urls = [f"/api/{n}" for n in range(10)]
results = asyncio.run(fetch_all(urls))

Asynchronous runtimes & concurrency

Nothing runs until you start a loop

Eager Promises, lazy coroutines

Combinators

Structured concurrency with TaskGroup

The GIL

Kata

On this page