Low-level extension API
This extension API is available through the
It allows you to hook directly into the Numba compilation chain. As such,
it distinguished between several compilation phases:
The typing phase deduces the types of variables in a compiled function by looking at the operations performed.
The lowering phase converts high-level Python operations into low-level LLVM code. This phase exploits the typing information derived by the typing phase.
Boxing and unboxing convert Python objects into native values, and vice-versa. They occur at the boundaries of calling a Numba function from the Python interpreter.
Type inference – or simply typing – is the process of assigning Numba types to all values involved in a function, so as to enable efficient code generation. Broadly speaking, typing comes in two flavours: typing plain Python values (e.g. function arguments or global variables) and typing operations (or functions) on known value types.
Register the decorated function as typing Python values of class cls. The decorated function will be called with the signature
(val, c)where val is the Python value being typed and c is a context object.
Register the decorated function as typing the callable func. func can be either an actual Python callable or a string denoting a operation internally known to Numba (for example
'getitem'). The decorated function is called with a single context argument and must return a typer function. The typer function should have the same signature as the function being typed, and it is called with the Numba types of the function arguments; it should return either the Numba type of the function’s return value, or
Noneif inference failed.
- as_numba_type.register(py_type, numba_type)
Register that the Python type py_type corresponds with the Numba type numba_type. This can be used to register a new type or overwrite the existing default (e.g. to treat
This function can also be used as a decorator. It registers the decorated function as a type inference function used by
as_numba_typewhen trying to infer the Numba type of a Python type. The decorated function is called with a single py_type argument and returns either a corresponding Numba type, or
Noneif it cannot infer that py_type.
The following decorators all take a type specification of some kind.
A type specification is usually a type class (such as
or a specific type instance (such as
types.float64). Some values
have a special meaning:
types.Anymatches any type; this allows doing your own dispatching inside the implementation
types.VarArg(<some type>)matches any number of arguments of the given type; it can only appear as the last type specification when describing a function’s arguments.
A context argument in the following APIs is a target context providing
various utility methods for code generation (such as creating a constant,
converting from a type to another, looking up the implementation of a
specific function, etc.). A builder argument is a
llvmlite.ir.IRBuilder instance for the LLVM code being generated.
A signature is an object specifying the concrete type of an operation.
args attribute of the signature is a tuple of the argument types.
return_type attribute of the signature is the type that the
operation should return.
Numba always reasons on Numba types, but the values being passed around during lowering are LLVM values: they don’t hold the required type information, which is why Numba types are passed explicitly too.
LLVM has its own, very low-level type system: you can access the LLVM
type of a value by looking up its
- @lower_builtin(func, typespec, ...)
Register the decorated function as implementing the callable func for the arguments described by the given Numba typespecs. As with
type_callable(), func can be either an actual Python callable or a string denoting a operation internally known to Numba (for example
The decorated function is called with four arguments
(context, builder, sig, args).
sigis the concrete signature the callable is being invoked with.
argsis a tuple of the values of the arguments the callable is being invoked with; each value in
argscorresponds to a type in
sig.args. The function must return a value compatible with the type
- @lower_getattr(typespec, name)
Register the decorated function as implementing the attribute name of the given typespec. The decorated function is called with four arguments
(context, builder, typ, value). typ is the concrete type the attribute is being looked up on. value is the value the attribute is being looked up on.
Register the decorated function as a fallback for attribute lookup on a given typespec. Any attribute that does not have a corresponding
lower_getattr()declaration will go through
lower_getattr_generic(). The decorated function is called with five arguments
(context, builder, typ, value, name). typ and value are as in
lower_getattr(). name is the name of the attribute being looked up.
- @lower_cast(fromspec, tospec)
Register the decorated function as converting from types described by fromspec to types described by tospec. The decorated function is called with five arguments
(context, builder, fromty, toty, value). fromty and toty are the concrete types being converted from and to, respectively. value is the value being converted. The function must return a value compatible with the type
Register the decorated function as implementing the creation of constants for the Numba typespec. The decorated function is called with four arguments
(context, builder, ty, pyval). ty is the concrete type to create a constant for. pyval is the Python value to convert into a LLVM constant. The function must return a value compatible with the type
Boxing and unboxing
In these functions, c is a convenience object with several attributes:
contextattribute is a target context as above
builderattribute is a
pyapiattribute is an object giving access to a subset of the Python interpreter’s C API
An object, as opposed to a native value, is a
PyObject * pointer.
Such pointers can be produced or processed by the methods in the
Register the decorated function as boxing values matching the typespec. The decorated function is called with three arguments
(typ, val, c). typ is the concrete type being boxed. val is the value being boxed. The function should return a Python object, or NULL to signal an error.
Register the decorated function as unboxing values matching the typespec. The decorated function is called with three arguments
(typ, obj, c). typ is the concrete type being unboxed. obj is the Python object (a
PyObject *pointer, in C terms) being unboxed. The function should return a
NativeValueobject giving the unboxing result value and an optional error bit.