Repository: numba/numba

Issue:
Decide whether or not to support the target kwarg in the numba.jit decorator
In a couple of issues, e.g. #5868, users have reported that using the `target=` kwarg for the `numba.jit` decorator doesn't always work. While this isn't documented on the website ([website docs](http://numba.pydata.org/numba-doc/latest/reference/jit-compilation.html#numba.jit)), it is documented in the docstring, and so anyone running `numba.njit?` in `ipython` or Jupyter will find it. An excerpt from the docstring is below:
```
    target: str
        Specifies the target platform to compile for. Valid targets are cpu,
        gpu, npyufunc, and cuda. Defaults to cpu.
```

So, there is a decision to be made. Does the Numba team support the kwarg (which means writing tests, fixing up bugs etc.), or not (which means deprecation and removal).


Discussion:
Thanks for raising this. I think e.g. `'gpu'` is not a target, the rest are valid as there are function registries for these and we should see if they working/if it makes sense for the code path to exist. 

Resolving patch:
diff --git a/numba/core/decorators.py b/numba/core/decorators.py
--- a/numba/core/decorators.py
+++ b/numba/core/decorators.py
@@ -23,7 +23,7 @@
                                  "Signatures should be passed as the first "
                                  "positional argument.")
 
-def jit(signature_or_function=None, locals={}, target='cpu', cache=False,
+def jit(signature_or_function=None, locals={}, cache=False,
         pipeline_class=None, boundscheck=False, **options):
     """
     This decorator is used to compile a Python function into native code.
@@ -41,7 +41,7 @@ def jit(signature_or_function=None, locals={}, target='cpu', cache=False,
         Mapping of local variable names to Numba types. Used to override the
         types deduced by Numba's type inference engine.
 
-    target: str
+    target (deprecated): str
         Specifies the target platform to compile for. Valid targets are cpu,
         gpu, npyufunc, and cuda. Defaults to cpu.
 
@@ -145,6 +145,11 @@ def bar(x, y):
         raise DeprecationError(_msg_deprecated_signature_arg.format('restype'))
     if options.get('nopython', False) and options.get('forceobj', False):
         raise ValueError("Only one of 'nopython' or 'forceobj' can be True.")
+    if 'target' in options:
+        target = options.pop('target')
+        warnings.warn("The 'target' keyword argument is deprecated.", NumbaDeprecationWarning)
+    else:
+        target = options.pop('_target', 'cpu')
 
     options['boundscheck'] = boundscheck
 
diff --git a/numba/np/ufunc/dufunc.py b/numba/np/ufunc/dufunc.py
--- a/numba/np/ufunc/dufunc.py
+++ b/numba/np/ufunc/dufunc.py
@@ -79,7 +79,7 @@ class DUFunc(_internal._DUFunc):
     def __init__(self, py_func, identity=None, cache=False, targetoptions={}):
         if isinstance(py_func, Dispatcher):
             py_func = py_func.py_func
-        dispatcher = jit(target='npyufunc',
+        dispatcher = jit(_target='npyufunc',
                          cache=cache,
                          **targetoptions)(py_func)
         self._initialize(dispatcher, identity)
diff --git a/numba/np/ufunc/ufuncbuilder.py b/numba/np/ufunc/ufuncbuilder.py
--- a/numba/np/ufunc/ufuncbuilder.py
+++ b/numba/np/ufunc/ufuncbuilder.py
@@ -227,7 +227,7 @@ class UFuncBuilder(_BaseUFuncBuilder):
     def __init__(self, py_func, identity=None, cache=False, targetoptions={}):
         self.py_func = py_func
         self.identity = parse_identity(identity)
-        self.nb_func = jit(target='npyufunc',
+        self.nb_func = jit(_target='npyufunc',
                            cache=cache,
                            **targetoptions)(py_func)
         self._sigs = []
@@ -292,7 +292,7 @@ def __init__(self, py_func, signature, identity=None, cache=False,
                  targetoptions={}):
         self.py_func = py_func
         self.identity = parse_identity(identity)
-        self.nb_func = jit(target='npyufunc', cache=cache)(py_func)
+        self.nb_func = jit(_target='npyufunc', cache=cache)(py_func)
         self.signature = signature
         self.sin, self.sout = parse_signature(signature)
         self.targetoptions = targetoptions


Test patch: