There are rare but real cases when a nopython-mode function needs to callback into the Python interpreter to invoke code that cannot be compiled by Numba. Such cases include:
When Numba callbacks into the Python interpreter, the following has to happen:
These steps can be expensive. Users should not rely on the feature described here on performance-critical paths.
objmode
context-manager¶Warning
This feature can be easily mis-used. Users should first consider alternative approaches to achieve their intended goal before using this feature.
numba.
objmode
(*args, **kwargs)¶Creates a contextmanager to be used inside jitted functions to enter object-mode for using interpreter features. The body of the with-context is lifted into a function that is compiled in object-mode. This transformation process is limited and cannot process all possible Python code. However, users can wrap complicated logic in another Python function, which will then be executed by the interpreter.
Use this as a function that takes keyword arguments only. The argument names must correspond to the output variables from the with-block. Their respective values are strings representing the expected types. When exiting the with-context, the output variables are cast to the expected nopython types according to the annotation. This process is the same as passing Python objects into arguments of a nopython function.
Example:
import numpy as np
from numba import njit, objmode
def bar(x):
# This code is executed by the interpreter.
return np.asarray(list(reversed(x.tolist())))
@njit
def foo():
x = np.arange(5)
y = np.zeros_like(x)
with objmode(y='intp[:]'): # annotate return type
# this region is executed by object-mode.
y += bar(x)
return y
Note
Known limitations:
yield
, break
, return
or raise
such that the execution will leave the with-block immediately.Note
When used outside of no-python mode, the context-manager has no effect.
Warning
This feature is experimental. The supported features may change with or without notice.