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

[llvmlistbot at llvm.org]

https://github.com/PragmaTwice created https://github.com/llvm/llvm-project/pull/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.


>From a333b14c15f3fffeabfa314cad6cf7ed71daabf6 Mon Sep 17 00:00:00 2001
From: Twice <twice at apache.org>
Date: Fri, 10 Oct 2025 16:58:59 +0800
Subject: [PATCH 1/2] [MLIR][Docs] Add docs for Python-defined pass in Python
 bindings

---
 mlir/docs/Bindings/Python.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/mlir/docs/Bindings/Python.md b/mlir/docs/Bindings/Python.md
index 98ac635aa4ee2..173b7d35e9ab3 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
 

>From 02c4f94422c3c3afd0d1e114f4cb072cbca125d2 Mon Sep 17 00:00:00 2001
From: Twice <twice at apache.org>
Date: Fri, 10 Oct 2025 17:01:44 +0800
Subject: [PATCH 2/2] refine code example

---
 mlir/docs/Bindings/Python.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mlir/docs/Bindings/Python.md b/mlir/docs/Bindings/Python.md
index 173b7d35e9ab3..893c6d48a88d2 100644
--- a/mlir/docs/Bindings/Python.md
+++ b/mlir/docs/Bindings/Python.md
@@ -1204,7 +1204,7 @@ def demo_pass(op, pass_):
 
 pm = PassManager('any')
 pm.add(demo_pass)
-pm.add('some-cpp-defined-passes..')
+pm.add('some-cpp-defined-passes')
 ...
 pm.run(some_op)
 ```