2.6. Supported Python features¶

2.6.1.1. Constructs¶

Numba strives to support as much of the Python language as possible, but some language features are not available inside Numba-compiled functions. Below is a quick reference for the support level of Python constructs.

Supported constructs:

• conditional branch: if .. elif .. else
• loops: while, for .. in, break, continue
• basic generator: yield
• assertion: assert

Partially supported constructs:

• exceptions: try .. except, raise (See details in this section)
• context manager: with (only support numba.objmode())
• list comprehension (see details in this section)

Unsupported constructs:

• async features: async with, async for and async def
• class definition: class (except for @jitclass)
• set, dict and generator comprehensions
• generator delegation: yield from

2.6.1.2. Functions¶

from numba import jit

@jit
def add1(x):
    return x + 1

@jit
def bar(fn, x):
    return fn(x)

@jit
def foo(x):
    return bar(add1, x)

# Passing add1 within numba compiled code.
print(foo(1))
# Passing add1 into bar from interpreted code
print(bar(add1, 1))

2.6.1.3. Generators¶

Numba supports generator functions and is able to compile them in object mode and nopython mode. The returned generator can be used both from Numba-compiled code and from regular Python code.

Coroutine features of generators are not supported (i.e. the generator.send(), generator.throw(), generator.close() methods).

2.6.1.4. Exception handling¶

try:
   do_work()
except Exception:
   handle_error_case()
   return error_code

2.6.2.1. int, bool¶

Arithmetic operations as well as truth values are supported.

The following attributes and methods are supported:

• .conjugate()
• .real
• .imag

2.6.2.2. float, complex¶

Arithmetic operations as well as truth values are supported.

The following attributes and methods are supported:

• .conjugate()
• .real
• .imag

2.6.2.3. str¶

Numba supports (Unicode) strings in Python 3. Strings can be passed into nopython mode as arguments, as well as constructed and returned from nopython mode. As in Python, slices (even of length 1) return a new, reference counted string. Optimized code paths for efficiently accessing single characters may be introduced in the future.

The in-memory representation is the same as was introduced in Python 3.4, with each string having a tag to indicate whether the string is using a 1, 2, or 4 byte character width in memory. When strings of different encodings are combined (as in concatenation), the resulting string automatically uses the larger character width of the two input strings. String slices also use the same character width as the original string, even if the slice could be represented with a narrower character width. (These details are invisible to the user, of course.)

The following functions, attributes and methods are currently supported:

• len()
• + (concatenation of strings)
• * (repetition of strings)
• in, .contains()
• ==, <, <=, >, >= (comparison)
• .capitalize()
• .casefold()
• .center()
• .count()
• .endswith()
• .endswith()
• .expandtabs()
• .find()
• .index()
• .isalnum()
• .isalpha()
• .isdecimal()
• .isdigit()
• .isidentifier()
• .islower()
• .isnumeric()
• .isprintable()
• .isspace()
• .istitle()
• .isupper()
• .join()
• .ljust()
• .lower()
• .lstrip()
• .partition()
• .replace()
• .rfind()
• .rindex()
• .rjust()
• .rpartition()
• .rsplit()
• .rstrip()
• .split()
• .splitlines()
• .startswith()
• .strip()
• .swapcase()
• .title()
• .upper()
• .zfill()

Additional operations as well as support for Python 2 strings / Python 3 bytes will be added in a future version of Numba. Python 2 Unicode objects will likely never be supported.

2.6.2.4. tuple¶

Tuple support is categorised into two categories based on the contents of a tuple. The first category is homogeneous tuples, these are tuples where the type of all the values in the tuple are the same, the second is heterogeneous tuples, these are tuples where the types of the values are different.

2.6.2.5. homogeneous tuples¶

An example of a homogeneous tuple:

homogeneous_tuple = (1, 2, 3, 4)

The following operations are supported on homogeneous tuples:

• Tuple construction.
• Tuple unpacking.
• Comparison between tuples.
• Iteration and indexing.
• Addition (concatenation) between tuples.
• Slicing tuples with a constant slice.
• The index method on tuples.

2.6.2.6. heterogeneous tuples¶

An example of a heterogeneous tuple:

heterogeneous_tuple = (1, 2j, 3.0, "a")

The following operations are supported on heterogeneous tuples:

• Comparison between tuples.
• Indexing using an index value that is a compile time constant e.g. mytuple[7], where 7 is evidently a constant.
• Iteration over a tuple (requires experimental literal_unroll() feature, see below).

To permit iteration over a heterogeneous tuple the special function numba.literal_unroll() must be used. This function has no effect other than to act as a token to permit the use of this feature. Example use:

from numba import njit, literal_unroll

@njit
def foo()
    heterogeneous_tuple = (1, 2j, 3.0, "a")
    for i in literal_unroll(heterogeneous_tuple):
        print(i)

A more involved use of literal_unroll() might be type specific dispatch, recall that string and integer literal values are considered their own type, for example:

from numba import njit, types, literal_unroll
from numba.extending import overload

def dt(x):
    # dummy function to overload
    pass

@overload(dt, inline='always')
def ol_dt(li):
    if isinstance(li, types.StringLiteral):
        value = li.literal_value
        if value == "apple":
            def impl(li):
                return 1
        elif value == "orange":
            def impl(li):
                return 2
        elif value == "banana":
            def impl(li):
                return 3
        return impl
    elif isinstance(li, types.IntegerLiteral):
        value = li.literal_value
        if value == 0xca11ab1e:
            def impl(li):
                # capture the dispatcher literal value
                return 0x5ca1ab1e + value
            return impl

@njit
def foo():
    acc = 0
    for t in literal_unroll(('apple', 'orange', 'banana', 3390155550)):
        acc += dt(t)
    return acc

print(foo())

2.6.2.7. list¶

Creating and returning lists from JIT-compiled functions is supported, as well as all methods and operations. Lists must be strictly homogeneous: Numba will reject any list containing objects of different types, even if the types are compatible (for example, [1, 2.5] is rejected as it contains a int and a float).

For example, to create a list of arrays:

In [1]: from numba import njit

In [2]: import numpy as np

In [3]: @njit
  ...: def foo(x):
  ...:     lst = []
  ...:     for i in range(x):
  ...:         lst.append(np.arange(i))
  ...:     return lst
  ...:

In [4]: foo(4)
Out[4]: [array([], dtype=int64), array([0]), array([0, 1]), array([0, 1, 2])]

In [1]: from numba.typed import List

In [2]: from numba import njit

In [3]: @njit
...: def foo(l):
...:     l.append(23)
...:     return l
...:

In [4]: mylist = List()

In [5]: mylist.append(1)

In [6]: foo(mylist)
Out[6]: ListType[int64]([1, 23])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from numba import njit
from numba.typed import List

@njit
def foo():
    # Instantiate a typed-list
    l = List()
    # Append a value to it, this will set the type to int32/int64 (depending on platform)
    l.append(42)
    # The usual list operations, getitem, pop and length are supported
    print(l[0])   # 42
    l[0] = 23
    print(l[0])   # 23
    print(len(l)) # 1
    l.pop()
    print(len(l)) # 0
    return l

mylist = foo()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

from numba import njit
from numba.typed import List

@njit
def foo(mylist):
    for i in range(10, 20):
        mylist.append()
    return mylist

# Instantiate a typed-list, outside of a jit context
l = List()
# Append a value to it, this will set the type to int32/int64 (depending on platform)
l.append(42)
# The usual list operations, getitem, pop and length are supported
print(l[0])   # 42
l[0] = 23
print(l[0])   # 23
print(len(l)) # 1
l.pop()
print(len(l)) # 0

# And you can use the typed-list as an argument for a jit compiled function

l = foo(l)
print(len(l)) # 10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from numba.typed import List

# typed-lists can be nested in typed-lists
mylist = List()
for i in range(10):
    l = List()
    for i in range(10):
        l.append(i)
    mylist.append(l)
# mylist is now a list of 10 lists, each containing 10 integers
print(mylist)

In [1]: from numba import njit

In [2]: @njit
  ...: def foo(x):
  ...:     return [[i for i in range(n)] for n in range(x)]
  ...:

In [3]: foo(3)
Out[3]: [[], [0], [0, 1]]

from numba import jit
import numpy as np

@jit(nopython=True)
def f(n):
  return np.array([ [ x * y for x in range(n) ] for y in range(n) ])

2.6.2.8. set¶

All methods and operations on sets are supported in JIT-compiled functions.

Sets must be strictly homogeneous: Numba will reject any set containing objects of different types, even if the types are compatible (for example, {1, 2.5} is rejected as it contains a int and a float).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from numba import njit
import numpy as np

@njit
def foo():
    d = dict()
    k = {1: np.arange(1), 2: np.arange(2)}
    # The following tells the compiler what the key type and the value
    # type are for `d`.
    d[3] = np.arange(3)
    d[5] = np.arange(5)
    return d, k

d, k = foo()
print(d)    # {3: [0 1 2], 5: [0 1 2 3 4]}
print(k)    # {1: [0], 2: [0 1]}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

import numpy as np
from numba import njit
from numba import types
from numba.typed import Dict

# The Dict.empty() constructs a typed dictionary.
# The key and value typed must be explicitly declared.
d = Dict.empty(
    key_type=types.unicode_type,
    value_type=types.float64[:],
)

# The typed-dict can be used from the interpreter.
d['posx'] = np.asarray([1, 0.5, 2], dtype='f8')
d['posy'] = np.asarray([1.5, 3.5, 2], dtype='f8')
d['velx'] = np.asarray([0.5, 0, 0.7], dtype='f8')
d['vely'] = np.asarray([0.2, -0.2, 0.1], dtype='f8')

# Here's a function that expects a typed-dict as the argument
@njit
def move(d):
    # inplace operations on the arrays
    d['posx'] += d['velx']
    d['posy'] += d['vely']

print('posx: ', d['posx'])  # Out: posx:  [1.  0.5 2. ]
print('posy: ', d['posy'])  # Out: posy:  [1.5 3.5 2. ]

# Call move(d) to inplace update the arrays in the typed-dict.
move(d)

print('posx: ', d['posx'])  # Out: posx:  [1.5 0.5 2.7]
print('posy: ', d['posy'])  # Out: posy:  [1.7 3.3 2.1]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import numpy as np
from numba import njit
from numba import types
from numba.typed import Dict

# Make array type.  Type-expression is not supported in jit functions.
float_array = types.float64[:]

@njit
def foo():
    # Make dictionary
    d = Dict.empty(
        key_type=types.unicode_type,
        value_type=float_array,
    )
    # Fill the dictionary
    d["posx"] = np.arange(3).astype(np.float64)
    d["posy"] = np.arange(3, 6).astype(np.float64)
    return d

d = foo()
# Print the dictionary
print(d)  # Out: {posx: [0. 1. 2.], posy: [3. 4. 5.]}

2.6.2.9. None¶

The None value is supported for identity testing (when using an optional type).

2.6.2.10. bytes, bytearray, memoryview¶

The bytearray type and, on Python 3, the bytes type support indexing, iteration and retrieving the len().

The memoryview type supports indexing, slicing, iteration, retrieving the len(), and also the following attributes:

• contiguous
• c_contiguous
• f_contiguous
• itemsize
• nbytes
• ndim
• readonly
• shape
• strides

2.6.3.1. Hashing¶

The hash() built-in is supported and produces hash values for all supported hashable types with the following Python version specific behavior:

Under Python 3, hash values computed by Numba will exactly match those computed in CPython under the condition that the sys.hash_info.algorithm is siphash24 (default).

The PYTHONHASHSEED environment variable influences the hashing behavior in precisely the manner described in the CPython documentation.

2.6.4.1. array¶

Limited support for the array.array type is provided through the buffer protocol. Indexing, iteration and taking the len() is supported. All type codes are supported except for "u".

2.6.4.2. cmath¶

The following functions from the cmath module are supported:

• cmath.acos()
• cmath.acosh()
• cmath.asin()
• cmath.asinh()
• cmath.atan()
• cmath.atanh()
• cmath.cos()
• cmath.cosh()
• cmath.exp()
• cmath.isfinite()
• cmath.isinf()
• cmath.isnan()
• cmath.log()
• cmath.log10()
• cmath.phase()
• cmath.polar()
• cmath.rect()
• cmath.sin()
• cmath.sinh()
• cmath.sqrt()
• cmath.tan()
• cmath.tanh()

2.6.4.3. collections¶

Named tuple classes, as returned by collections.namedtuple(), are supported in the same way regular tuples are supported. Attribute access and named parameters in the constructor are also supported.

Creating a named tuple class inside Numba code is not supported; the class must be created at the global level.

2.6.4.4. ctypes¶

Numba is able to call ctypes-declared functions with the following argument and return types:

• ctypes.c_int8
• ctypes.c_int16
• ctypes.c_int32
• ctypes.c_int64
• ctypes.c_uint8
• ctypes.c_uint16
• ctypes.c_uint32
• ctypes.c_uint64
• ctypes.c_float
• ctypes.c_double
• ctypes.c_void_p

2.6.4.5. enum¶

Both enum.Enum and enum.IntEnum subclasses are supported.

2.6.4.6. math¶

The following functions from the math module are supported:

• math.acos()
• math.acosh()
• math.asin()
• math.asinh()
• math.atan()
• math.atan2()
• math.atanh()
• math.ceil()
• math.copysign()
• math.cos()
• math.cosh()
• math.degrees()
• math.erf()
• math.erfc()
• math.exp()
• math.expm1()
• math.fabs()
• math.floor()
• math.frexp()
• math.gamma()
• math.gcd()
• math.hypot()
• math.isfinite()
• math.isinf()
• math.isnan()
• math.ldexp()
• math.lgamma()
• math.log()
• math.log10()
• math.log1p()
• math.pow()
• math.radians()
• math.sin()
• math.sinh()
• math.sqrt()
• math.tan()
• math.tanh()
• math.trunc()

2.6.4.7. operator¶

The following functions from the operator module are supported:

• operator.add()
• operator.and_()
• operator.eq()
• operator.floordiv()
• operator.ge()
• operator.gt()
• operator.iadd()
• operator.iand()
• operator.ifloordiv()
• operator.ilshift()
• operator.imatmul() (Python 3.5 and above)
• operator.imod()
• operator.imul()
• operator.invert()
• operator.ior()
• operator.ipow()
• operator.irshift()
• operator.isub()
• operator.itruediv()
• operator.ixor()
• operator.le()
• operator.lshift()
• operator.lt()
• operator.matmul() (Python 3.5 and above)
• operator.mod()
• operator.mul()
• operator.ne()
• operator.neg()
• operator.not_()
• operator.or_()
• operator.pos()
• operator.pow()
• operator.rshift()
• operator.sub()
• operator.truediv()
• operator.xor()

2.6.4.8. functools¶

The functools.reduce() function is supported but the initializer argument is required.

2.6.4.9. random¶

Numba supports top-level functions from the random module, but does not allow you to create individual Random instances. A Mersenne-Twister generator is used, with a dedicated internal state. It is initialized at startup with entropy drawn from the operating system.

• random.betavariate()
• random.expovariate()
• random.gammavariate()
• random.gauss()
• random.getrandbits(): number of bits must not be greater than 64
• random.lognormvariate()
• random.normalvariate()
• random.paretovariate()
• random.randint()
• random.random()
• random.randrange()
• random.seed(): with an integer argument only
• random.shuffle(): the sequence argument must be a one-dimension Numpy array or buffer-providing object (such as a bytearray or array.array); the second (optional) argument is not supported
• random.uniform()
• random.triangular()
• random.vonmisesvariate()
• random.weibullvariate()

2.6.4.10. heapq¶

The following functions from the heapq module are supported:

• heapq.heapify()
• heapq.heappop()
• heapq.heappush()
• heapq.heappushpop()
• heapq.heapreplace()
• heapq.nlargest() : first two arguments only
• heapq.nsmallest() : first two arguments only

Note: the heap must be seeded with at least one value to allow its type to be inferred; heap items are assumed to be homogeneous in type.

2.6.5.1. cffi¶

Similarly to ctypes, Numba is able to call into cffi-declared external functions, using the following C types and any derived pointer types:

• char
• short
• int
• long
• long long
• unsigned char
• unsigned short
• unsigned int
• unsigned long
• unsigned long long
• int8_t
• uint8_t
• int16_t
• uint16_t
• int32_t
• uint32_t
• int64_t
• uint64_t
• float
• double
• ssize_t
• size_t
• void

The from_buffer() method of cffi.FFI and CompiledFFI objects is supported for passing Numpy arrays and other buffer-like objects. Only contiguous arguments are accepted. The argument to from_buffer() is converted to a raw pointer of the appropriate C type (for example a double * for a float64 array).

Additional type mappings for the conversion from a buffer to the appropriate C type may be registered with Numba. This may include struct types, though it is only permitted to call functions that accept pointers to structs - passing a struct by value is unsupported. For registering a mapping, use:

numba.cffi_support.register_type(cffi_type, numba_type)¶

Out-of-line cffi modules must be registered with Numba prior to the use of any of their functions from within Numba-compiled functions:

numba.cffi_support.register_module(mod)¶

Register the cffi out-of-line module mod with Numba.

Inline cffi modules require no registration.