[Mlir-commits] [mlir] 19b9b54 - [MLIR][Docs] Add docs for Python-defined pass in Python bindings (#162833)

[llvmlistbot at llvm.org]

Author: Twice
Date: 2025-10-11T09:04:02+08:00
New Revision: 19b9b54158b9d4653e26f02981e43b6f45048e55

URL: https://github.com/llvm/llvm-project/commit/19b9b54158b9d4653e26f02981e43b6f45048e55
DIFF: https://github.com/llvm/llvm-project/commit/19b9b54158b9d4653e26f02981e43b6f45048e55.diff

LOG: [MLIR][Docs] Add docs for Python-defined pass in Python bindings (#162833)

Python-defined passes have been merged into the main branch for some
time now. I believe adding a corresponding section in the documentation
will help more users learn about this feature and understand how to use
it.

This PR adds such a section to the docs of Python bindings, summarizing
the feature and providing an example.

Added: 
    

Modified: 
    mlir/docs/Bindings/Python.md

Removed: 
    


################################################################################
diff  --git a/mlir/docs/Bindings/Python.md b/mlir/docs/Bindings/Python.md
index 98ac635aa4ee2..893c6d48a88d2 100644
--- a/mlir/docs/Bindings/Python.md
+++ b/mlir/docs/Bindings/Python.md
@@ -1188,6 +1188,26 @@ which can be `import`ed  from the main dialect file, i.e.
 `python/mlir/dialects/<dialect-namespace>/passes.py` if it is undesirable to
 make the passes available along with the dialect.
 
+Passes can be defined as Python callables via the `PassManager.add` API.
+In such case, the callable is wrapped as an `mlir::Pass` internally and
+executed as part of the pass pipeline when `PassManager.run` is invoked.
+In the callable, the `op` parameter represents the current operation being transformed,
+while the `pass_` parameter provides access to the current `Pass` object,
+allowing actions such as `signalPassFailure()`.
+The lifetime of the callable is extended at least until the `PassManager` is destroyed.
+The following example code demonstrates how to define Python passes.
+
+```python
+def demo_pass(op, pass_):
+    # do something with the given op
+    pass
+
+pm = PassManager('any')
+pm.add(demo_pass)
+pm.add('some-cpp-defined-passes')
+...
+pm.run(some_op)
+```
 
 ### Other functionality