[Mlir-commits] [mlir] [MLIR][Docs] Add docs about Python-defined dialects (PR #181372)

[llvmlistbot at llvm.org]

https://github.com/PragmaTwice created https://github.com/llvm/llvm-project/pull/181372

This PR adds documentation to the MLIR Python bindings introducing support for Python-defined dialects (initially introduced in #169045).


>From 685b2d675a158438a5b1fcbb31b62d49329f9b6d Mon Sep 17 00:00:00 2001
From: Twice <twice at apache.org>
Date: Fri, 13 Feb 2026 23:12:22 +0800
Subject: [PATCH 1/2] [MLIR][Docs] Add docs about Python-defined dialects

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

diff --git a/mlir/docs/Bindings/Python.md b/mlir/docs/Bindings/Python.md
index f75febd1a06e0..eff9e28973f00 100644
--- a/mlir/docs/Bindings/Python.md
+++ b/mlir/docs/Bindings/Python.md
@@ -1293,7 +1293,41 @@ The following sections outline how each of these can be implemented.
 
 ### Dialects
 
-Dialects can be defined through the IRDL dialect bindings in Python.
+The `mlir.dialects.ext` module provides support for defining Python-defined dialects.
+Users can define a new dialect (e.g., `MyDialect`) by subclassing the `Dialect` class,
+and define operations in that dialect by subclassing `MyDialect.Operation`.
+The dialect can then be loaded into MLIR by calling `MyDialect.load()` within a valid `Context`.
+After loading, these operations can be used just like other `OpView` subclasses.
+
+The following example shows how to define a dialect and construct IR using the newly defined ops.
+
+```python
+class MyInt(Dialect, name="myint"):
+    pass
+
+class ConstantOp(MyInt.Operation, name="constant"):
+    value: IntegerAttr
+    cst: Result[IntegerType[32]]
+
+class AddOp(MyInt.Operation, name="add"):
+    lhs: Operand[IntegerType[32]]
+    rhs: Operand[IntegerType[32]]
+    res: Result[IntegerType[32]]
+
+# The code below requires an available MLIR context and location.
+
+MyInt.load()
+
+module = Module.create()
+with InsertionPoint(module.body):
+    two = ConstantOp(IntegerAttr.get(i32, 2))
+    three = ConstantOp(IntegerAttr.get(i32, 3))
+    add1 = AddOp(two, three)
+    add2 = AddOp(add1, two)
+    add3 = AddOp(add2, three)
+```
+
+Dialects can also be defined directly through the IRDL dialect bindings in Python.
 The IRDL bindings offer a `load_dialects` function that
 converts an MLIR module containing `irdl.dialect` ops into MLIR dialects.
 For further details, see the documentation of [the IRDL dialect](../Dialects/IRDL.md).

>From 2bcc2c7d9ac5af576b43b5dc3dd7fc7cc0e7bf1f Mon Sep 17 00:00:00 2001
From: Twice <twice at apache.org>
Date: Fri, 13 Feb 2026 23:15:43 +0800
Subject: [PATCH 2/2] fix wording

---
 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 eff9e28973f00..3af91e7a4cba8 100644
--- a/mlir/docs/Bindings/Python.md
+++ b/mlir/docs/Bindings/Python.md
@@ -1327,7 +1327,7 @@ with InsertionPoint(module.body):
     add3 = AddOp(add2, three)
 ```
 
-Dialects can also be defined directly through the IRDL dialect bindings in Python.
+Dialects can also be defined through the IRDL dialect bindings in Python.
 The IRDL bindings offer a `load_dialects` function that
 converts an MLIR module containing `irdl.dialect` ops into MLIR dialects.
 For further details, see the documentation of [the IRDL dialect](../Dialects/IRDL.md).