[API Compatibility] Change compatibility apis to ChangePrefixMatcher, inject paddle.enable_compat() -part

paconvert/transformer/import_transformer.py

@@ -46,6 +46,9 @@ def __init__(
         self.imports_map[self.file]["api_alias_name_map"] = {}
         self.insert_pass_node = set()
         self.change_prefix_api_map = defaultdict(set)
+        # Set in visit_Module: True when this file actually imports torch (so we
+        # added paddle imports) and therefore needs paddle.enable_compat injected.
+        self.need_enable_compat = False
 
     def visit_Import(self, node):
         """
@@ -525,3 +528,94 @@ def visit_Module(self, node):
                 (self.root, "body", 0), ast.parse(f"import {paddle_package}").body
             )
             line_NO += 1
+
+        # enable_compat is injected in transform() (needs all imports in the body).
+        # Gate on real torch imports, not paddle_package_list: the latter also holds
+        # MAY_TORCH packages (os/einops/setuptools) that need no compat switch.
+        if self.imports_map[self.file]["torch_packages"]:
+            self.need_enable_compat = True
+
+    def transform(self):
+        super(ImportTransformer, self).transform()
+        self._inject_enable_compat()
+
+    @staticmethod
+    def _is_future_import(node):
+        return isinstance(node, ast.ImportFrom) and node.module == "__future__"
+
+    @staticmethod
+    def _is_import(node):
+        return isinstance(node, (ast.Import, ast.ImportFrom))
+
+    @staticmethod
+    def _is_docstring(node):
+        return (
+            isinstance(node, ast.Expr)
+            and isinstance(node.value, ast.Constant)
+            and isinstance(node.value.value, str)
+        )
+
+    @staticmethod
+    def _is_enable_compat_call(node):
+        return (
+            isinstance(node, ast.Expr)
+            and isinstance(node.value, ast.Call)
+            and isinstance(node.value.func, ast.Attribute)
+            and node.value.func.attr == "enable_compat"
+            and isinstance(node.value.func.value, ast.Name)
+            and node.value.func.value.id == "paddle"
+        )
+
+    @staticmethod
+    def _binds_paddle(node):
+        # `import paddle` or `import paddle.xxx` (no asname) binds the name `paddle`
+        if isinstance(node, ast.Import):
+            for alias_node in node.names:
+                if alias_node.asname is None and (
+                    alias_node.name == "paddle" or alias_node.name.startswith("paddle.")
+                ):
+                    return True
+        return False
+
+    def _inject_enable_compat(self):
+        """Insert ``paddle.enable_compat(level=2)`` after the docstring,
+        ``__future__`` imports and the import block (level=2 aliases the
+        torch-aligned ``paddle.compat.*`` APIs onto ``paddle.*``). Post-pass so it
+        is never placed above a ``__future__`` import (which is a SyntaxError).
+        """
+        if not self.need_enable_compat:
+            return
+
+        body = [n for n in self.root.body if not self._is_enable_compat_call(n)]
+
+        # hoist all __future__ imports (they must precede every other statement)
+        futures = [n for n in body if self._is_future_import(n)]
+        body = [n for n in body if not self._is_future_import(n)]
+
+        # hoist the module docstring if only imports precede it (we prepend imports)
+        doc = []
+        for i, node in enumerate(body):
+            if self._is_docstring(node) and all(self._is_import(n) for n in body[:i]):
+                doc = [node]
+                body = body[:i] + body[i + 1 :]
+                break
+
+        # split off the contiguous import block at the top of the remainder
+        end = 0
+        while end < len(body) and self._is_import(body[end]):
+            end += 1
+        imports, rest = body[:end], body[end:]
+
+        # enable_compat needs the name `paddle` bound (submodule-only aliases may
+        # not bind it, e.g. `import torch.nn as nn` -> `import paddle.nn as nn`)
+        if not any(self._binds_paddle(n) for n in imports):
+            imports = ast.parse("import paddle").body + imports
+
+        compat = ast.parse("paddle.enable_compat(level=2)").body
+        self.root.body = doc + futures + imports + compat + rest
+        ast.fix_missing_locations(self.root)
+        log_info(
+            self.logger,
+            "add 'paddle.enable_compat(level=2)' after imports",
+            self.file_name,
+        )

tests/apibase.py

@@ -20,6 +20,9 @@
 import numpy as np
 
 sys.path.append(os.path.dirname(__file__) + "/..")
+sys.path.append(os.path.dirname(__file__))
+
+from conftest import disable_paddle_compat
 
 from paconvert.converter import Converter
 
@@ -85,6 +88,7 @@ def run(
                 )
                 assert paddle_code == expect_paddle_code, error_msg
         elif compared_tensor_names:
+            disable_paddle_compat()
             pytorch_ns = {}
             try:
                 exec(pytorch_code, pytorch_ns)
@@ -117,6 +121,7 @@ def run(
                 except Exception as e:
                     raise AssertionError(f"Unable to align results: {e}")
         else:
+            disable_paddle_compat()
             pytorch_ns = {}
             try:
                 exec(pytorch_code, pytorch_ns)

tests/conftest.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 PaddlePaddle Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+
+import pytest
+
+
+def disable_paddle_compat():
+    """Turn OFF Paddle's torch-compat proxy if it is currently active.
+
+    Converted Paddle code injects ``paddle.enable_compat(level=2)``, which flips
+    process-global state: it installs an ``import torch`` -> Paddle proxy and
+    aliases ``paddle.*`` to the torch-aligned ``paddle.compat.*`` APIs. That state
+    must be cleared so it cannot leak into (a) a later test, or (b) a torch
+    *reference* run within the same test, whose ``import torch`` would otherwise be
+    proxied to Paddle so the reference would no longer be real torch.
+
+    Lazy and best-effort: a no-op when Paddle was never imported, so it does not
+    force a Paddle import (and thus does not change torch/paddle import ordering)
+    for tests that never touch Paddle.
+    """
+    if "paddle" not in sys.modules:
+        return
+    paddle = sys.modules["paddle"]
+    try:
+        from paddle.compat.proxy import TORCH_PROXY_FINDER
+
+        while TORCH_PROXY_FINDER in sys.meta_path:
+            paddle.disable_compat()
+    except Exception:
+        pass
+
+
+@pytest.fixture(autouse=True)
+def _reset_paddle_compat_mode():
+    """Disable torch-compat after every test so it cannot leak into a later one."""
+    yield
+    disable_paddle_compat()

tests/test_Tensor_median.py

@@ -38,12 +38,7 @@ def test_case_2():
         result = input.median(1)
         """
     )
-    obj.run(
-        pytorch_code,
-        ["result"],
-        unsupport=True,
-        reason="paddle does not return index when dim is specified",
-    )
+    obj.run(pytorch_code, ["result"])
 
 
 def test_case_3():
@@ -54,12 +49,7 @@ def test_case_3():
         result = input.median(1, keepdim=True)
         """
     )
-    obj.run(
-        pytorch_code,
-        ["result"],
-        unsupport=True,
-        reason="paddle does not return index when dim is specified",
-    )
+    obj.run(pytorch_code, ["result"])
 
 
 def test_case_4():
@@ -70,12 +60,7 @@ def test_case_4():
         result = input.median(dim=1, keepdim=True)
         """
     )
-    obj.run(
-        pytorch_code,
-        ["result"],
-        unsupport=True,
-        reason="paddle does not return index when dim is specified",
-    )
+    obj.run(pytorch_code, ["result"])
 
 
 def test_case_5():
@@ -86,9 +71,26 @@ def test_case_5():
         result = input.median(0)
         """
     )
-    obj.run(
-        pytorch_code,
-        ["result"],
-        unsupport=True,
-        reason="paddle does not return index when dim is specified",
+    obj.run(pytorch_code, ["result"])
+
+
+def test_case_6():
+    pytorch_code = textwrap.dedent(
+        """
+        import torch
+        input = torch.tensor([1.0, 2.0, 3.0, 4.0])
+        result = input.median()
+        """
     )
+    obj.run(pytorch_code, ["result"])
+
+
+def test_case_7():
+    pytorch_code = textwrap.dedent(
+        """
+        import torch
+        input = torch.tensor([[1.0, 2.0, 3.0, 4.0], [8.0, 7.0, 6.0, 5.0]])
+        result = input.median(dim=1)
+        """
+    )
+    obj.run(pytorch_code, ["result"])

tests/test_Tensor_rename.py

@@ -29,7 +29,13 @@ def test_case_1():
     )
     obj.run(
         pytorch_code,
-        expect_paddle_code='import paddle\n\nx = paddle.tensor([1, 2, 3])\nx.rename(columns={"iids": iids})\n',
+        expect_paddle_code="""
+import paddle
+
+paddle.enable_compat(level=2)
+x = paddle.tensor([1, 2, 3])
+x.rename(columns={"iids": iids})
+            """,
     )
 
 

tests/test_Tensor_split.py

@@ -100,6 +100,7 @@ def test_case_7():
         """
         import paddle
 
+        paddle.enable_compat(level=2)
         a = paddle.tensor([1, 2, 3])
         str1 = "1,2,3"
         str1.split(",")

tests/test_add_start_docstrings_to_model_forward.py

@@ -36,6 +36,8 @@ def forward(self, input_ids):
         import paddle
         import paddleformers
 
+        paddle.enable_compat(level=2)
+
 
         class LlamaForCausalLM(paddle.nn.Module):
             @paddleformers.trainer.utils.add_start_docstrings_to_model_forward("test docstring")

tests/test_jit_ignore.py

@@ -43,6 +43,8 @@ def helper_function(self, x):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         class MyModule(paddle.nn.Module):
             def forward(self, x):

tests/test_jit_load.py

@@ -31,6 +31,7 @@ def test_case_1():
         """
         import paddle
 
+        paddle.enable_compat(level=2)
         result = paddle.jit.load(path="model.pt")
         """
     )
@@ -48,6 +49,7 @@ def test_case_2():
         """
         import paddle
 
+        paddle.enable_compat(level=2)
         result = paddle.jit.load(path="model.pt")
         """
     )

tests/test_jit_save.py

@@ -45,6 +45,8 @@ def forward(self, x):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         class MyModule(paddle.nn.Module):
             def __init__(self):
@@ -89,6 +91,8 @@ def forward(self, x):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         class MyModule(paddle.nn.Module):
             def __init__(self):
@@ -134,6 +138,8 @@ def forward(self, x):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         class MyModule(paddle.nn.Module):
             def __init__(self):
@@ -180,6 +186,8 @@ def forward(self, x):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         class MyModule(paddle.nn.Module):
             def __init__(self):

tests/test_jit_script.py

@@ -34,6 +34,8 @@ def foo(x, scale, shift):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         @paddle.jit.to_static
         def foo(x, scale, shift):
@@ -66,6 +68,8 @@ def add(x, y):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         def add(x, y):
             return x + y
@@ -99,6 +103,8 @@ def add(x, y):
         """
         import paddle
 
+        paddle.enable_compat(level=2)
+
 
         def add(x, y):
             return x + y

tests/test_onnx_export.py

@@ -105,12 +105,14 @@ def onnx_export(model,f):
         ############################## 相关utils函数，如上 ##############################
 
 
+        paddle.enable_compat(level=2)
+
 
         class SimpleModel(paddle.nn.Module):
             def __init__(self):
                 super(SimpleModel, self).__init__()
-                self.fc1 = paddle.compat.nn.Linear(3, 3)
-                self.fc2 = paddle.compat.nn.Linear(3, 1)
+                self.fc1 = paddle.nn.Linear(3, 3)
+                self.fc2 = paddle.nn.Linear(3, 1)
 
             def forward(self, x):
                 x = paddle.relu(self.fc1(x))