inst defintion and its optional stack_effect

The DSL specification syntax definition of the inst shows that the stack_effect is optional,
including its parentheses:

definition:
    "inst" "(" NAME ["," stack_effect] ")" "{" C-code "}"
...
stack_effect:
    "(" [inputs] "--" [outputs] ")"

But if we defined a new instruction, let's say, MY_INSTRUCTION as:

inst(MY_INSTRUCTION) {
  /* implementation */
}

We will get the following error:

SyntaxError: Extra stuff at the end of ./Python/bytecodes.c

However, if we defined MY_INSTRUCTION with an empty stack-effect, it will work!

inst(MY_INSTRUCTION, ( -- )) {
  /* implementation */
}

Linked PRs

@brandtbucher

@brandtbucher

I think it's easier to change the docs than to change the parser. And it's better, IMO, to keep an explicit stack effect as it helps readability and avoids having special cases during parsing.

@picnixz

@picnixz I agree. Clearly defining the stack effect and enforcing it at the parser level will help ensure consistency in the inst definition across all instructions.

@picnixz

The inst_header method of the parser shows that it is not dealing with the optional path. However, it will be enough to update the doc.

@contextual
def inst_header(self) -> InstHeader | None:
    # annotation* inst(NAME, (inputs -- outputs))
    # | annotation* op(NAME, (inputs -- outputs))
    annotations = []
    while anno := self.expect(lx.ANNOTATION):
        if anno.text == "replicate":
            self.require(lx.LPAREN)
            times = self.require(lx.NUMBER)
            self.require(lx.RPAREN)
            annotations.append(f"replicate({times.text})")
        else:
            annotations.append(anno.text)
    tkn = self.expect(lx.INST)
    if not tkn:
        tkn = self.expect(lx.OP)
    if tkn:
        kind = cast(Literal["inst", "op"], tkn.text)
        if self.expect(lx.LPAREN) and (tkn := self.expect(lx.IDENTIFIER)):
            name = tkn.text
            if self.expect(lx.COMMA):
                inp, outp = self.io_effect()
                if self.expect(lx.RPAREN):
                    if (tkn := self.peek()) and tkn.kind == lx.LBRACE:
                        return InstHeader(annotations, kind, name, inp, outp)
    return None

@picnixz @tomasr8

I think it should be enough to update the internal docs. I don't think there's any urgent need to support the optional syntax (imo, it's better to be explicit)

pythongh-133412: remove the brackets of the optional stack_effect

I haven't merged your PR yet :). I'm only merging PRs when I'm on my Linux session and before 8PM (Paris time)

gh-133412: amend docs for the `inst` definition (#133708)

pythongh-133412: amend docs for the `inst` definition (pythonGH-133708)

[3.14] gh-133412: amend docs for the `inst` definition (GH-133708) (#…

[3.13] gh-133412: amend docs for the `inst` definition (GH-133708) (#…

pythongh-133412: amend docs for the `inst` definition (python#133708)

Navigation Menu

Repository navigation

`inst` defintion and its optional `stack_effect` #133412

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

inst defintion and its optional stack_effect #133412

Description

Linked PRs

Activity

nybblista commented on May 5, 2025

picnixz commented on May 5, 2025

nybblista commented on May 5, 2025

nybblista commented on May 6, 2025

tomasr8 commented on May 6, 2025

picnixz commented on May 8, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

`inst` defintion and its optional `stack_effect` #133412