npmai-fast

Zero-dependency AST-to-native compiler for hot numeric Python functions.

from npmai_fast import optimize

@optimize
def total(a: int, b: int) -> int:
    result = 0
    for i in range(a):
        result += b
    return result

Just decorate and call. No config, no build step you have to run yourself.

What actually happens

On first call, the function's source is analyzed. If it fits the compilable numeric subset (int/float params and return, arithmetic, comparisons, if/while/for-range loops — see below), it is transpiled to C++20, compiled once with whatever compiler is on your machine (g++, clang++, or MSVC), cached in ~/.cache/npmai_fast/, and called natively through ctypes on every call after that.

If the function does not fit that subset (dicts, lists, generators, closures, exceptions, dynamic typing, etc.) — or no C++ compiler is installed — it transparently falls back to plain CPython. Same result, just not accelerated. This is by design: correctness first, speed second.

Supported today

• Parameters and return value annotated int or float
• + - * / // % ** (with correct Python floor-division/modulo semantics)
• Comparisons, and/or/not
• if/elif/else, while, for x in range(...)
• Single-name local variables (no re-typing a variable mid-function)

Not yet supported (falls back automatically, does not error)

• Lists, dicts, strings, objects, classes
• Function calls to anything other than range()
• Exceptions, generators, closures over outer state
• *args/**kwargs, default arguments

This puts npmai-fast in the same category as Numba's @njit or Pythran — a numeric hot-loop compiler, not a general Python-to-native compiler. The difference is a zero-dependency implementation (no LLVM) plus AST-level inlining planned for a future release.

CLI

npmai-fast check   # is a C++ compiler available on this machine?
npmai-fast stats   # cache size / compiled function count
npmai-fast clear   # wipe the compiled-function cache

Requirements

A C++20-capable compiler must be installed for acceleration to kick in:

• Linux: sudo apt install g++ (or your distro's equivalent)
• macOS: xcode-select --install
• Windows: Visual Studio Build Tools, "Desktop development with C++"

Without one, functions still run correctly — just as plain Python.