Skip to content

Warning

This page is under construction. The content may be incomplete or incorrect. Submit an issue on GitHub if you need help or want to contribute.

Dialects for Python Syntax Sugar

This page contains the dialects designed to represent Python syntax sugar. They provide an implementation of lowering transform from the corresponding Python AST to the dialects' statements. All the statements are typed Any thus one can always use a custom rewrite pass after type inference to support the desired syntax sugar.

Reference

Indexing

kirin.dialects.py.indexing

The indexing dialect for Python.

This module contains the dialect for the Python indexing syntax, including:

  • The GetItem statement class.
  • A base class Subscript for indexing statements.
  • A trait GetItemLike for indexing statements.
  • The lowering pass for the indexing statement.
  • The concrete implementation of the indexing statement.
  • The constant propagation implementation (special case) of the indexing statement.
  • The type inference implementation of the indexing statement.
  • A canonical rewrite rule for the rewriting of a given getitem-like statement to another getitem-like statement.

GetItemLikeStmt module-attribute 

GetItemLikeStmt = TypeVar(
    "GetItemLikeStmt", bound=Statement
)

PyGetItemLikeStmt module-attribute 

PyGetItemLikeStmt = TypeVar(
    "PyGetItemLikeStmt", bound="GetItem"
)

dialect module-attribute 

dialect = Dialect('py.indexing')

Concrete

Bases: MethodTable


              flowchart TD
              kirin.dialects.py.indexing.Concrete[Concrete]
              kirin.interp.table.MethodTable[MethodTable]

                              kirin.interp.table.MethodTable --> kirin.dialects.py.indexing.Concrete
                


              click kirin.dialects.py.indexing.Concrete href "" "kirin.dialects.py.indexing.Concrete"
              click kirin.interp.table.MethodTable href "" "kirin.interp.table.MethodTable"

getindex 

getindex(interp, frame: Frame, stmt: GetItem)
Source code in src/kirin/dialects/py/indexing.py 
 99
100
101
@interp.impl(GetItem)
def getindex(self, interp, frame: interp.Frame, stmt: GetItem):
    return (frame.get(stmt.obj)[frame.get(stmt.index)],)

ConstProp

Bases: MethodTable


              flowchart TD
              kirin.dialects.py.indexing.ConstProp[ConstProp]
              kirin.interp.table.MethodTable[MethodTable]

                              kirin.interp.table.MethodTable --> kirin.dialects.py.indexing.ConstProp
                


              click kirin.dialects.py.indexing.ConstProp href "" "kirin.dialects.py.indexing.ConstProp"
              click kirin.interp.table.MethodTable href "" "kirin.interp.table.MethodTable"

getitem 

getitem(
    _: Propagate, frame: Frame, stmt: GetItem
) -> interp.StatementResult[const.Result]
Source code in src/kirin/dialects/py/indexing.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
@interp.impl(GetItem)
def getitem(
    self,
    _: const.Propagate,
    frame: const.Frame,
    stmt: GetItem,
) -> interp.StatementResult[const.Result]:
    obj = frame.get(stmt.obj)
    index = frame.get(stmt.index)
    if not isinstance(index, const.Value):
        return (const.Unknown(),)

    if isinstance(obj, const.Value):
        return (const.Value(obj.data[index.data]),)
    elif isinstance(obj, const.PartialTuple):
        obj = obj.data
        if isinstance(index.data, int) and 0 <= index.data < len(obj):
            return (obj[index.data],)
        elif isinstance(index.data, slice):
            return (const.PartialTuple(obj[index.data]),)
    return (const.Unknown(),)

GetItem kirin-statement 

GetItem(obj: SSAValue, index: SSAValue)

Bases: Subscript


              flowchart TD
              kirin.dialects.py.indexing.GetItem[GetItem]
              kirin.dialects.py.indexing.Subscript[Subscript]
              kirin.ir.nodes.stmt.Statement[Statement]
              kirin.ir.nodes.base.IRNode[IRNode]
              kirin.print.printable.Printable[Printable]

                              kirin.dialects.py.indexing.Subscript --> kirin.dialects.py.indexing.GetItem
                                kirin.ir.nodes.stmt.Statement --> kirin.dialects.py.indexing.Subscript
                                kirin.ir.nodes.base.IRNode --> kirin.ir.nodes.stmt.Statement
                                kirin.print.printable.Printable --> kirin.ir.nodes.base.IRNode
                





              click kirin.dialects.py.indexing.GetItem href "" "kirin.dialects.py.indexing.GetItem"
              click kirin.dialects.py.indexing.Subscript href "" "kirin.dialects.py.indexing.Subscript"
              click kirin.ir.nodes.stmt.Statement href "" "kirin.ir.nodes.stmt.Statement"
              click kirin.ir.nodes.base.IRNode href "" "kirin.ir.nodes.base.IRNode"
              click kirin.print.printable.Printable href "" "kirin.print.printable.Printable"

index kirin-argument 

index: SSAValue = argument(print=False)

name class-attribute instance-attribute 

name = 'getitem'

obj kirin-argument 

obj: SSAValue = argument(print=False)

result kirin-result 

result: ResultValue = result(Any)

traits class-attribute instance-attribute 

traits = frozenset(
    {Pure(), PyGetItemLike(), FromPythonCall()}
)

GetItemLike dataclass 

GetItemLike()

Bases: Trait[Statement], Generic[GetItemLikeStmt]


              flowchart TD
              kirin.dialects.py.indexing.GetItemLike[GetItemLike]
              kirin.ir.traits.abc.Trait[Trait]

                              kirin.ir.traits.abc.Trait --> kirin.dialects.py.indexing.GetItemLike
                


              click kirin.dialects.py.indexing.GetItemLike href "" "kirin.dialects.py.indexing.GetItemLike"
              click kirin.ir.traits.abc.Trait href "" "kirin.ir.traits.abc.Trait"

get_index abstractmethod 

get_index(stmt: GetItemLikeStmt) -> ir.SSAValue
Source code in src/kirin/dialects/py/indexing.py 
38
39
@abstractmethod
def get_index(self, stmt: GetItemLikeStmt) -> ir.SSAValue: ...

get_object abstractmethod 

get_object(stmt: GetItemLikeStmt) -> ir.SSAValue
Source code in src/kirin/dialects/py/indexing.py 
35
36
@abstractmethod
def get_object(self, stmt: GetItemLikeStmt) -> ir.SSAValue: ...

new abstractmethod 

new(
    stmt_type: type[GetItemLikeStmt],
    obj: SSAValue,
    index: SSAValue,
) -> GetItemLikeStmt
Source code in src/kirin/dialects/py/indexing.py 
41
42
43
44
@abstractmethod
def new(
    self, stmt_type: type[GetItemLikeStmt], obj: ir.SSAValue, index: ir.SSAValue
) -> GetItemLikeStmt: ...

Lowering dataclass 

Lowering()

Bases: FromPythonAST


              flowchart TD
              kirin.dialects.py.indexing.Lowering[Lowering]
              kirin.lowering.python.dialect.FromPythonAST[FromPythonAST]

                              kirin.lowering.python.dialect.FromPythonAST --> kirin.dialects.py.indexing.Lowering
                


              click kirin.dialects.py.indexing.Lowering href "" "kirin.dialects.py.indexing.Lowering"
              click kirin.lowering.python.dialect.FromPythonAST href "" "kirin.lowering.python.dialect.FromPythonAST"

lower_Subscript 

lower_Subscript(
    state: State, node: Subscript
) -> lowering.Result
Source code in src/kirin/dialects/py/indexing.py 
84
85
86
87
88
89
90
91
92
93
def lower_Subscript(
    self, state: lowering.State, node: ast.Subscript
) -> lowering.Result:
    value = state.lower(node.value).expect_one()
    slice = state.lower(node.slice).expect_one()
    if isinstance(node.ctx, ast.Load):
        stmt = GetItem(obj=value, index=slice)
    else:
        raise lowering.BuildError(f"unsupported subscript context {node.ctx}")
    return state.current_frame.push(stmt)

PyGetItemLike dataclass 

PyGetItemLike()

Bases: GetItemLike[PyGetItemLikeStmt]


              flowchart TD
              kirin.dialects.py.indexing.PyGetItemLike[PyGetItemLike]
              kirin.dialects.py.indexing.GetItemLike[GetItemLike]
              kirin.ir.traits.abc.Trait[Trait]

                              kirin.dialects.py.indexing.GetItemLike --> kirin.dialects.py.indexing.PyGetItemLike
                                kirin.ir.traits.abc.Trait --> kirin.dialects.py.indexing.GetItemLike
                



              click kirin.dialects.py.indexing.PyGetItemLike href "" "kirin.dialects.py.indexing.PyGetItemLike"
              click kirin.dialects.py.indexing.GetItemLike href "" "kirin.dialects.py.indexing.GetItemLike"
              click kirin.ir.traits.abc.Trait href "" "kirin.ir.traits.abc.Trait"

get_index 

get_index(stmt: PyGetItemLikeStmt) -> ir.SSAValue
Source code in src/kirin/dialects/py/indexing.py 
56
57
def get_index(self, stmt: PyGetItemLikeStmt) -> ir.SSAValue:
    return stmt.index

get_object 

get_object(stmt: PyGetItemLikeStmt) -> ir.SSAValue
Source code in src/kirin/dialects/py/indexing.py 
53
54
def get_object(self, stmt: PyGetItemLikeStmt) -> ir.SSAValue:
    return stmt.obj

new 

new(
    stmt_type: type[PyGetItemLikeStmt],
    obj: SSAValue,
    index: SSAValue,
) -> PyGetItemLikeStmt
Source code in src/kirin/dialects/py/indexing.py 
59
60
61
62
def new(
    self, stmt_type: type[PyGetItemLikeStmt], obj: ir.SSAValue, index: ir.SSAValue
) -> PyGetItemLikeStmt:
    return stmt_type(obj=obj, index=index)

RewriteGetItem dataclass 

RewriteGetItem(
    stmt_type: type[GetItemLikeStmt],
    obj_type: TypeAttribute,
)

Bases: RewriteRule, Generic[GetItemLikeStmt]


              flowchart TD
              kirin.dialects.py.indexing.RewriteGetItem[RewriteGetItem]
              kirin.rewrite.abc.RewriteRule[RewriteRule]

                              kirin.rewrite.abc.RewriteRule --> kirin.dialects.py.indexing.RewriteGetItem
                


              click kirin.dialects.py.indexing.RewriteGetItem href "" "kirin.dialects.py.indexing.RewriteGetItem"
              click kirin.rewrite.abc.RewriteRule href "" "kirin.rewrite.abc.RewriteRule"
Source code in src/kirin/dialects/py/indexing.py 
230
231
232
233
234
235
236
237
def __init__(self, stmt_type: type[GetItemLikeStmt], obj_type: types.TypeAttribute):
    trait = stmt_type.get_trait(GetItemLike)
    if trait is None:
        raise ValueError(f"{stmt_type} does not have GetItemLike trait")

    self.obj_type = obj_type
    self.target_stmt_type = stmt_type
    self.getitem_like = trait

getitem_like instance-attribute 

getitem_like: GetItemLike[GetItemLikeStmt] = trait

obj_type instance-attribute 

obj_type: TypeAttribute = obj_type

target_stmt_type instance-attribute 

target_stmt_type: type[GetItemLikeStmt] = stmt_type

rewrite_Statement 

rewrite_Statement(node: Statement) -> RewriteResult
Source code in src/kirin/dialects/py/indexing.py 
239
240
241
242
243
244
245
246
247
248
249
def rewrite_Statement(self, node: ir.Statement) -> RewriteResult:
    if not isinstance(node, GetItem):
        return RewriteResult()

    if not node.obj.type.is_subseteq(self.obj_type):
        return RewriteResult()

    node.replace_by(
        self.getitem_like.new(self.target_stmt_type, node.obj, node.index)
    )
    return RewriteResult(has_done_something=True)

Subscript kirin-statement 

Subscript()

Bases: Statement


              flowchart TD
              kirin.dialects.py.indexing.Subscript[Subscript]
              kirin.ir.nodes.stmt.Statement[Statement]
              kirin.ir.nodes.base.IRNode[IRNode]
              kirin.print.printable.Printable[Printable]

                              kirin.ir.nodes.stmt.Statement --> kirin.dialects.py.indexing.Subscript
                                kirin.ir.nodes.base.IRNode --> kirin.ir.nodes.stmt.Statement
                                kirin.print.printable.Printable --> kirin.ir.nodes.base.IRNode
                




              click kirin.dialects.py.indexing.Subscript href "" "kirin.dialects.py.indexing.Subscript"
              click kirin.ir.nodes.stmt.Statement href "" "kirin.ir.nodes.stmt.Statement"
              click kirin.ir.nodes.base.IRNode href "" "kirin.ir.nodes.base.IRNode"
              click kirin.print.printable.Printable href "" "kirin.print.printable.Printable"

TypeInfer

Bases: MethodTable


              flowchart TD
              kirin.dialects.py.indexing.TypeInfer[TypeInfer]
              kirin.interp.table.MethodTable[MethodTable]

                              kirin.interp.table.MethodTable --> kirin.dialects.py.indexing.TypeInfer
                


              click kirin.dialects.py.indexing.TypeInfer href "" "kirin.dialects.py.indexing.TypeInfer"
              click kirin.interp.table.MethodTable href "" "kirin.interp.table.MethodTable"

getitem 

getitem(
    interp: TypeInference,
    frame: Frame[TypeAttribute],
    stmt: GetItem,
)
Source code in src/kirin/dialects/py/indexing.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@interp.impl(GetItem)
def getitem(
    self,
    interp: TypeInference,
    frame: interp.Frame[types.TypeAttribute],
    stmt: GetItem,
):
    obj = frame.get(stmt.obj)
    index: types.TypeAttribute = frame.get(stmt.index)
    # TODO: replace this when we can multiple dispatch
    if obj.is_subseteq(types.Tuple):
        return self.getitem_tuple(interp, stmt, obj, index)
    elif obj.is_subseteq(types.String):
        return (types.String,)
    else:
        return (types.Any,)

getitem_tuple 

getitem_tuple(
    interp,
    stmt: GetItem,
    obj: TypeAttribute,
    index: TypeAttribute,
)
Source code in src/kirin/dialects/py/indexing.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
def getitem_tuple(
    self,
    interp,
    stmt: GetItem,
    obj: types.TypeAttribute,
    index: types.TypeAttribute,
):
    if isinstance(obj, types.Generic):
        if index.is_subseteq(types.Int):
            return self.getitem_tuple_index(interp, stmt, obj, index)
        elif index.is_subseteq(types.Slice):
            return self.getitem_tuple_slice(interp, stmt, obj, index)
        else:
            return (types.Bottom,)
    elif isinstance(obj, types.PyClass):
        return (types.Any,)
    else:
        return (types.Bottom,)

getitem_tuple_index 

getitem_tuple_index(
    interp: TypeInference,
    stmt: GetItem,
    obj: Generic,
    index: TypeAttribute,
)
Source code in src/kirin/dialects/py/indexing.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def getitem_tuple_index(
    self,
    interp: TypeInference,
    stmt: GetItem,
    obj: types.Generic,
    index: types.TypeAttribute,
):
    if index_ := interp.maybe_const(stmt.index, int):
        if obj.vararg and (index_ >= len(obj.vars) or -len(obj.vars) <= index_ < 0):
            return (obj.vararg.typ,)
        elif obj.vars and (
            0 <= index_ < len(obj.vars) or -len(obj.vars) <= index_ < 0
        ):
            return (obj.vars[index_],)
        else:
            return (types.Bottom,)
    else:
        return (self.getitem_tuple_union(obj),)

getitem_tuple_slice 

getitem_tuple_slice(
    interp: TypeInference,
    stmt: GetItem,
    obj: Generic,
    index: TypeAttribute,
)
Source code in src/kirin/dialects/py/indexing.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
def getitem_tuple_slice(
    self,
    interp: TypeInference,
    stmt: GetItem,
    obj: types.Generic,
    index: types.TypeAttribute,
):
    if index_ := interp.maybe_const(stmt.index, slice):
        if obj.vararg and index_.stop >= len(obj.vars):
            return (
                types.Union(
                    *obj.vars[slice(index_.start, len(obj.vars), index_.step)],
                    obj.vararg.typ,
                ),
            )
        elif index_.stop is None or index_.stop < len(obj.vars):
            return (
                types.Tuple.where(
                    obj.vars[slice(index_.start, index_.stop, index_.step)]
                ),
            )
        else:  # out of bounds
            return (types.Bottom,)
    else:
        return (types.Tuple[types.Vararg(self.getitem_tuple_union(obj))],)

getitem_tuple_union 

getitem_tuple_union(obj: Generic)
Source code in src/kirin/dialects/py/indexing.py 
188
189
190
191
192
def getitem_tuple_union(self, obj: types.Generic):
    if obj.vararg:
        return types.Union(*obj.vars, obj.vararg.typ)
    else:
        return types.Union(*obj.vars)

Attribute

kirin.dialects.py.attr

Attribute access dialect for Python.

This module contains the dialect for the Python attribute access statement, including:

  • The GetAttr statement class.
  • The lowering pass for the attribute access statement.
  • The concrete implementation of the attribute access statement.

This dialect maps ast.Attribute nodes to the GetAttr statement.

dialect module-attribute 

dialect = Dialect('py.attr')

Concrete

Bases: MethodTable


              flowchart TD
              kirin.dialects.py.attr.Concrete[Concrete]
              kirin.interp.table.MethodTable[MethodTable]

                              kirin.interp.table.MethodTable --> kirin.dialects.py.attr.Concrete
                


              click kirin.dialects.py.attr.Concrete href "" "kirin.dialects.py.attr.Concrete"
              click kirin.interp.table.MethodTable href "" "kirin.interp.table.MethodTable"

getattr 

getattr(interp: Interpreter, frame: Frame, stmt: GetAttr)
Source code in src/kirin/dialects/py/attr.py 
32
33
34
@interp.impl(GetAttr)
def getattr(self, interp: interp.Interpreter, frame: interp.Frame, stmt: GetAttr):
    return (getattr(frame.get(stmt.obj), stmt.attrname),)

GetAttr kirin-statement 

GetAttr(obj: SSAValue, *, attrname: str)

Bases: Statement


              flowchart TD
              kirin.dialects.py.attr.GetAttr[GetAttr]
              kirin.ir.nodes.stmt.Statement[Statement]
              kirin.ir.nodes.base.IRNode[IRNode]
              kirin.print.printable.Printable[Printable]

                              kirin.ir.nodes.stmt.Statement --> kirin.dialects.py.attr.GetAttr
                                kirin.ir.nodes.base.IRNode --> kirin.ir.nodes.stmt.Statement
                                kirin.print.printable.Printable --> kirin.ir.nodes.base.IRNode
                




              click kirin.dialects.py.attr.GetAttr href "" "kirin.dialects.py.attr.GetAttr"
              click kirin.ir.nodes.stmt.Statement href "" "kirin.ir.nodes.stmt.Statement"
              click kirin.ir.nodes.base.IRNode href "" "kirin.ir.nodes.base.IRNode"
              click kirin.print.printable.Printable href "" "kirin.print.printable.Printable"

attrname kirin-attribute kw-only 

attrname: str = attribute()

name class-attribute instance-attribute 

name = 'getattr'

obj kirin-argument 

obj: SSAValue = argument(print=False)

result kirin-result 

result: ResultValue = result()

traits class-attribute instance-attribute 

traits = frozenset({FromPythonCall()})

Lowering dataclass 

Lowering()

Bases: FromPythonAST


              flowchart TD
              kirin.dialects.py.attr.Lowering[Lowering]
              kirin.lowering.python.dialect.FromPythonAST[FromPythonAST]

                              kirin.lowering.python.dialect.FromPythonAST --> kirin.dialects.py.attr.Lowering
                


              click kirin.dialects.py.attr.Lowering href "" "kirin.dialects.py.attr.Lowering"
              click kirin.lowering.python.dialect.FromPythonAST href "" "kirin.lowering.python.dialect.FromPythonAST"

lower_Attribute 

lower_Attribute(
    state: State, node: Attribute
) -> lowering.Result
Source code in src/kirin/dialects/py/attr.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def lower_Attribute(
    self, state: lowering.State, node: ast.Attribute
) -> lowering.Result:

    if not isinstance(node.ctx, ast.Load):
        raise lowering.BuildError(f"unsupported attribute context {node.ctx}")

    # NOTE: eagerly load global variables
    value = state.get_global(node, no_raise=True)
    if value is not None:
        return state.lower(ast.Constant(value.data)).expect_one()

    value = state.lower(node.value).expect_one()
    return state.current_frame.push(GetAttr(obj=value, attrname=node.attr))