[Lang] Deprecate ti.experimental.real_func (#8409)

Issue: #

### Brief Summary

<!--
copilot:summary
-->
### <samp>🤖[[deprecated]](https://githubnext.com/copilot-for-prs-sunset)
Generated by Copilot at b4b5bd9</samp>

Moved `real_func` decorator to `ti.experimental` and added deprecation
warning. Added test case for `real_func` functionality and warning.

### Walkthrough

<!--
copilot:walkthrough
-->
### <samp>🤖[[deprecated]](https://githubnext.com/copilot-for-prs-sunset)
Generated by Copilot at b4b5bd9</samp>

* Move `real_func` decorator from `taichi.lang.kernel_impl` to
`taichi.experimental` and add deprecation warning
([link](https://github.com/taichi-dev/taichi/pull/8409/files?diff=unified&w=0#diff-60267f25c1e1dfada9487235a4a793b63a49aa3d33c93b8449e24ac821a33174L1-R8),
[link](https://github.com/taichi-dev/taichi/pull/8409/files?diff=unified&w=0#diff-e0e39c57bc92c0e1da4c831f8820a4082a3cc26a9b88962bee72964dfa26a74aL13-R13))
* Add test case for `ti.experimental.real_func` functionality and
warning
([link](https://github.com/taichi-dev/taichi/pull/8409/files?diff=unified&w=0#diff-8981be068a363e39524dc2e29d28d4c13a097d0037fc3a1176b249ce5bf35ef8L96-R117))

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

python/taichi/__init__.py

@@ -10,7 +10,7 @@
 from taichi.types.primitive_types import *
 
 
-from taichi import ad, algorithms, graph, linalg, math, sparse, tools, types
+from taichi import ad, algorithms, experimental, graph, linalg, math, sparse, tools, types
 from taichi.ui import GUI, hex_to_rgb, rgb_to_hex, ui
 
 # Issue#2223: Do not reorder, or we're busted with partially initialized module

python/taichi/experimental.py

@@ -0,0 +1,13 @@
+from taichi.lang.kernel_impl import real_func as _real_func
+import warnings
+
+
+def real_func(func):
+    warnings.warn(
+        "ti.experimental.real_func is deprecated because it is no longer experimental. " "Use ti.real_func instead.",
+        DeprecationWarning,
+    )
+    return _real_func(func)
+
+
+__all__ = ["real_func"]

tests/python/test_api.py

@@ -129,6 +129,7 @@ def _get_expected_matrix_apis():
     "dx12",
     "eig",
     "exp",
+    "experimental",
     "extension",
     "f16",
     "f32",

tests/python/test_deprecation.py

@@ -93,3 +93,28 @@ def test_deprecate_initialization_of_scene():
         match=r"Instantiating ti.ui.Scene directly is deprecated, use the get_scene\(\) function from a taichi.ui.Window object instead.",
     ):
         ti.ui.Scene()
+
+
+@test_utils.test(arch=[ti.cpu, ti.cuda])
+def test_deprecate_experimental_real_func():
+    with pytest.warns(
+        DeprecationWarning,
+        match="ti.experimental.real_func is deprecated because it is no longer experimental. "
+        "Use ti.real_func instead.",
+    ):
+
+        @ti.experimental.real_func
+        def foo(a: ti.i32) -> ti.i32:
+            s = 0
+            for i in range(100):
+                if i == a + 1:
+                    return s
+                s = s + i
+            return s
+
+        @ti.kernel
+        def bar(a: ti.i32) -> ti.i32:
+            return foo(a)
+
+        assert bar(10) == 11 * 5
+        assert bar(200) == 99 * 50