Lines Matching +full:python +full:- +full:version
1 # MLIR Python Bindings
9 ### Pre-requisites
12 * Installation of python dependencies as specified in
13 `mlir/python/requirements.txt`
19 Enables building the Python bindings. Defaults to `OFF`.
23 Specifies the `python` executable used for the LLVM build, including for
24 determining header/link flags for the Python bindings. On systems with
25 multiple Python implementations, setting this explicitly to the preferred
30 It is recommended to use a python virtual environment. Many ways exist for this,
34 # Make sure your 'python' is what you expect. Note that on multi-python
35 # systems, this may have a version suffix, and on many Linuxes and MacOS where
36 # python2 and python3 co-exist, you may also want to use `python3`.
37 which python
38 python -m venv ~/.venv/mlirdev
41 # Note that many LTS distros will bundle a version of pip itself that is too
43 # The pip version can be obtained with `python -m pip --version`, and for
47 python -m pip install --upgrade pip
50 # Now the `python` command will resolve to your virtual environment and
52 python -m pip install -r mlir/python/requirements.txt
65 Note that if you have installed (i.e. via `ninja install`, et al), then python
74 There are likely two primary use cases for the MLIR python bindings:
76 1. Support users who expect that an installed version of LLVM/MLIR will yield
81 with other python native bits.
85 In order to support use case \#2, the Python bindings are organized into
86 composable modules that downstream integrators can include and re-export into
92 * Introduce headers for C++-only wrapper classes as other related C++ modules
99 There are a lot of co-related issues of shared library linkage, distribution
103 meta-programming in pybind scales with the number of things you define in a
110 However, in order to modularize and make the Python bindings easier to
111 understand, sub-packages are defined that map roughly to the directory structure
130 LLVM/MLIR is a non-trivial python-native project that is likely to co-exist with
131 other non-trivial native extensions. As such, the native extension (i.e. the
132 `.so`/`.pyd`/`.dylib`) is exported as a notionally private top-level symbol
133 (`_mlir`), while a small set of Python code is provided in
134 `mlir/_cext_loader.py` and siblings which loads and re-exports it. This split
136 the shared library is loaded into the Python runtime, and also provides a place
137 that one-time initialization code can be invoked apart from module constructors.
146 https://packaging.python.org/guides/packaging-namespace-packages/
148 ### Use the C-API
150 The Python APIs should seek to layer on top of the C-API to the degree possible.
151 Especially for the core, dialect-independent parts, such a binding enables
153 boundary. In addition, factoring in this way side-steps some very difficult
154 issues that arise when combining RTTI-based modules (which pybind derived things
155 are) with non-RTTI polymorphic C++ code (the default compilation mode of LLVM).
159 There are several top-level types in the core IR that are strongly owned by
160 their python-side reference:
164 * `PyOperation` (`mlir.ir.Operation`) - but with caveats
166 All other objects are dependent. All objects maintain a back-reference
167 (keep-alive) to their closest containing top-level object. Further, dependent
168 objects fall into two categories: a) uniqued (which live for the life-time of
170 keeping track of when the C++ instance that backs their Python object is no
192 The rationale for this is that in Python, trailing keyword arguments to the
205 top-level or dependent state. The life-cycle is unidirectional: operations can
206 be created detached (top-level) and once added to another operation, they are
211 the IR with a parent of their outer-most detached operation, but then once it is
212 added to an attached operation, they need to be re-parented to the containing
216 for regions and blocks and needs to be a top-level type that we can count on not
221 never more than one Python `mlir.ir.Operation` object for a unique
227 The aliasing of Python `Region`/`Block` instances to underlying
231 If we ever want to re-introduce detached regions/blocks, we could do so with new
234 blocks. We may end up needing an op-local one at some point TBD, depending on
235 how hard it is to guarantee how mutations interact with their Python peer
238 Module, when used purely from the Python API, can't alias anyway, so we can use
239 it as a top-level ref type without a live-list for interning. If the API ever
241 native-defined Module in), then there would need to be a live table for it too.
243 ## User-level API
247 The bindings rely on Python
248 [context managers](https://docs.python.org/3/reference/datamodel.html#context-managers)
257 An MLIR context is a top-level entity that owns attributes and types and is
259 at the C++ level. In Python bindings, the MLIR context is also a Python context
262 ```python
273 `.context` property. Most IR-constructing functions expect the context to be
286 ```python
307 - an *insertion point* that indicates where the operation is to be created in
311 - a *location* that contains user-understandable information about the source
319 ```python
347 ```python
356 referenced from somewhere in Python code.
362 for top-level operations that contain the IR, such as modules. Regions, blocks
367 Inspecting the IR is one of the primary tasks the Python bindings are designed
375 - the generic `Operation` class, useful in particular for generic processing
377 - a specific subclass of `OpView` that provides more semantically-loaded
383 This typically means that the Python module of its dialect has been loaded. By
384 default, the `OpView` version is produced when navigating the IR tree.
386 One can check if an operation has a specific type by means of Python's
389 ```python
400 - `attributes` is a collection of operation attributes . It can be subscripted
405 - `operands` is a sequence collection of operation operands.
406 - `results` is a sequence collection of operation results.
407 - `regions` is a sequence collection of regions attached to the operation.
412 ```python
425 `operation.attributes["const_value"]`. If this name is a reserved Python
431 ```python
443 ```python
455 Block and region belong to the parent operation in Python bindings and keep it
460 Attributes and types are (mostly) immutable context-owned objects. They are
463 - an opaque `Attribute` or `Type` object supporting printing and comparison;
465 - a concrete subclass thereof with access to properties of the attribute or
472 ```python
489 ```python
506 Concrete attribute and type classes usually expose their properties as Python
516 - a generic `Value` object; or
517 - a concrete `BlockArgument` or `OpResult` object.
525 ```python
543 interfaces are available as Python classes with the same name as their C++
546 - an object of the `Operation` class or of any `OpView` subclass; in this
548 - a subclass of `OpView` and a context; in this case, only the *static*
557 ```python
598 Only a subset of operation interfaces are currently provided in Python bindings.
599 Attribute and type interfaces are not yet available in Python bindings.
603 Python bindings also support IR creation and manipulation.
614 - an optional sequence of types for operation results (`results`);
615 - an optional sequence of values for operation operands, or another operation
617 - an optional dictionary of operation attributes (`attributes`);
618 - an optional sequence of successor blocks (`successors`);
619 - the number of regions to attach to the operation (`regions`, default `0`);
620 - the `loc` keyword argument containing the `Location` of this operation; if
623 - the `ip` keyword argument indicating where the operation will be inserted in
629 arguments that are relevant for the operation. For example, zero-result
632 example, built-in function operations can be constructed by providing a function
635 ```python
654 ```python
672 are not constructible in Python and are not expected to exist outside of
681 ```python
709 ```python
713 # through another context-owned object.
726 ```python
734 Builtin attribute can often be constructed from Python types with similar
738 ```python
750 ```python
759 ```python
763 The registration is based on the ODS name but registry is via pure python
770 ```python
776 In general, for the core parts of MLIR, the Python bindings should be largely
784 `isEntryBlock()`, etc to read-only Python properties (i.e. `context`). It is
786 and makes things feel much nicer to the Python side.
804 to the `__repr__` method (and verify it with a [doctest](#sample-doctest)).
809 a mechanical concession to Python style, this can go a long way to making the
810 API feel like it fits in with its peers in the Python landscape.
813 [PEP 8 style names](https://pep8.org/#descriptive-naming-styles).
815 ### Prefer pseudo-containers
822 ```python
832 ```python
841 print(region.blocks[-1])
844 Instead of leaking STL-derived identifiers (`front`, `back`, etc), translate
848 arguments may appear container-like but have defined methods for lookup and
862 Tests should be added in the `test/Bindings/Python` directory and should
867 * For generative tests (those that produce IR), define a Python module that
869 * Parsing should be kept self-contained within the module under test by use of
873 * For convenience, we also test non-generative API interactions with the same
878 ```python
879 # RUN: %PYTHON %s | mlir-opt -split-input-file | FileCheck
884 print("// -----")
889 # CHECK-LABEL: TEST_FUNCTION: create_my_op
901 The MLIR Python bindings integrate with the tablegen-based ODS system for
902 providing user-friendly wrappers around MLIR dialects and operations. There are
904 elided: refer to the build rules and python sources under `mlir.dialects` for
912 Each dialect with a mapping to python requires that an appropriate
914 invoking `mlir-tblgen` on a python-bindings specific tablegen wrapper that
931 mlir-tblgen -gen-python-op-bindings -bind-dialect={DIALECT_NAMESPACE} \
938 ```python
944 When the python bindings need to locate a wrapper module, they consult the
946 main repository, this search path is hard-coded to include the `mlir.dialects`
950 ```python
967 Each concrete `OpView` subclass further defines several public-intended
974 * `@property` getter for each operand or result (using an auto-generated name
978 It further emits additional private-intended attributes meant for subclassing
987 * `_ODS_OPERAND_SEGMENTS` and `_ODS_RESULT_SEGMENTS`: Black-box value which
1000 * For single-valued results: Each will accept an `mlir.ir.Type`.
1003 * For single-valued operands: Each will accept an `mlir.ir.Value`.
1006 * Trailing usage-specific, optional keyword arguments:
1016 operations that are otherwise unsupported in Python, at the expense of having a
1021 As mentioned above, the build system generates Python sources like
1022 `_{DIALECT_NAMESPACE}_ops_gen.py` for each dialect with Python bindings. It is
1028 ```python
1039 Thus, a natural extension is a builder that accepts a MLIR type and a Python value and instantiates the appropriate `TypedAttr`:
1041 ```python
1063 ```python
1074 3. in order to register `ConstantOpExt` as the preferred `OpView` that is returned by `mlir.ir.Operation.opview` (see [Operations, Regions and Blocks](#operations-regions-and-blocks))
1077 In some more complex cases it might be necessary to explicitly build the `OpView` through `OpView.build_generic` (see [Default Builder](#default-builder)), just as is performed by the generated builders.
1081 ```python
1093 Note, there are alternatives ways to implement this (e.g., explicitly writing `OpView.__init__`); see any discussion on Python inheritance.
1095 ## Providing Python bindings for a dialect
1097 Python bindings are designed to support MLIR’s open dialect ecosystem. A dialect
1098 can be exposed to Python as a submodule of `mlir.dialects` and interoperate with
1100 sufficient to provide Python APIs for those operations. Note that the majority
1104 registered with the context in order to be usable in a text-specified pass
1105 manager, which may be done at Python module load time. Other functionality can
1107 building Python API on top.
1112 Dialect operations are provided in Python by wrapping the generic
1113 `mlir.ir.Operation` class with operation-specific builder functions and
1115 For operations defined in ODS, `mlir-tblgen -gen-python-op-bindings
1116 -bind-dialect=<dialect-namespace>` generates the Python API from the declarative
1119 definition and use it as source for the `mlir-tblgen` call.
1121 [`python/mlir/dialects/`](https://github.com/llvm/llvm-project/tree/main/mlir/python/mlir/dialects).
1122 The results of `mlir-tblgen` are expected to produce a file named
1123 `_<dialect-namespace>_ops_gen.py` by convention. The generated operation classes
1125 functions](https://github.com/llvm/llvm-project/blob/main/mlir/cmake/modules/AddMLIRPython.cmake)
1127 `python/mlir/dialects/<dialect-namespace>.py` or a
1128 `python/mlir/dialects/<dialect-namespace>/__init__.py` file must be created and
1130 mlir.dialects.<dialect-namespace>` in Python.
1135 Dialect attributes and types are provided in Python as subclasses of the
1136 `mlir.ir.Attribute` and `mlir.ir.Type` classes, respectively. Python APIs for
1140 [`include/mlir/Bindings/Python/PybindAdaptors.h`](https://github.com/llvm/llvm-project/blob/main/mlir/include/mlir/Bindings/Python/PybindAdaptors.h)
1142 [`include/mlir/Bindings/Python/NanobindAdaptors.h`](https://github.com/llvm/llvm-project/blob/main/mlir/include/mlir/Bindings/Python/NanobindAdaptors.h)
1146 and `MlirType` and their Python counterparts so that the C API handles can be
1151 `lib/Bindings/Python/Dialect<Name>.cpp` and should be compiled into a separate
1152 “Python extension” library placed in `python/mlir/_mlir_libs` that will be
1153 loaded by Python at runtime. MLIR provides [CMake
1154 functions](https://github.com/llvm/llvm-project/blob/main/mlir/cmake/modules/AddMLIRPython.cmake)
1156 from the main dialect file, i.e. `python/mlir/dialects/<dialect-namespace>.py`
1157 or `python/mlir/dialects/<dialect-namespace>/__init__.py`, to ensure the types
1158 are available when the dialect is loaded from Python.
1163 Dialect-specific passes can be made available to the pass manager in Python by
1166 pybind11 module, defined in `lib/Bindings/Python/<Dialect>Passes.cpp`, that
1168 declaratively using Tablegen, `mlir-tblgen -gen-pass-capi-header` and
1169 `-mlir-tblgen -gen-pass-capi-impl` automate the generation of C API. The
1170 pybind11 module must be compiled into a separate “Python extension” library,
1172 `python/mlir/dialects/<dialect-namespace>.py` or
1173 `python/mlir/dialects/<dialect-namespace>/__init__.py`, or from a separate
1175 `python/mlir/dialects/<dialect-namespace>/passes.py` if it is undesirable to
1182 can be exposed to Python similarly to attributes and types. C API is expected to
1184 [`include/mlir/Bindings/Python/PybindAdaptors.h`](https://github.com/llvm/llvm-project/blob/main/mlir/include/mlir/Bindings/Python/PybindAdaptors.h),
1186 [`include/mlir/Bindings/Python/NanobindAdaptors.h`](https://github.com/llvm/llvm-project/blob/main/mlir/include/mlir/Bindings/Python/NanobindAdaptors.h)
1187 utilities to connect to the rest of Python API. The bindings can be located in a
1191 ## Free-threading (No-GIL) support
1193 Free-threading or no-GIL support refers to CPython interpreter (>=3.13) with Global Interpreter Lock made optional. For details on the topic, please check [PEP-703](https://peps.python.org/pep-0703/) and this [Python free-threading guide](https://py-free-threading.github.io/).
1195 MLIR Python bindings are free-threading compatible with exceptions (discussed below) in the following sense: it is safe to work in multiple threads with **independent** contexts. Below we show an example code of safe usage:
1197 ```python
1224 The exceptions to the free-threading compatibility:
1225 - IR printing is unsafe, e.g. when using `PassManager` with `PassManager.enable_ir_printing()` which calls thread-unsafe `llvm::raw_ostream`.
1226 - Usage of `Location.emit_error` is unsafe (due to thread-unsafe `llvm::raw_ostream`).
1227 - Usage of `Module.dump` is unsafe (due to thread-unsafe `llvm::raw_ostream`).
1228 - Usage of `mlir.dialects.transform.interpreter` is unsafe.
1229 - Usage of `mlir.dialects.gpu` and `gpu-module-to-binary` is unsafe