---

name: python-ast-tooling description: "Use openqasm3 from Python to parse and print OpenQASM 3, construct and inspect its AST, traverse or conservatively transform nodes, and validate compiler-pass scaffolding with parse-print-reparse checks." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Python AST tooling

Use this sub-skill when the task mentions openqasm3, Python AST nodes, parse, dumps, source spans or comments, AST visitors, transformers, identifier rewrites, or a small compiler-pass scaffold. It covers the reference Python API, not a complete semantic compiler or a provider toolchain.

Route the work

• For normative language design, language-level idioms, or practical program patterns, hand off to language-authoring.
• For lexical rules, grammar acceptance, parser conformance fixtures, and the distinction between syntax and parser contextual checks, hand off to grammar-conformance.
• Do not use this skill for simulator/QPU execution, provider compilation, OpenQASM 2 migration, semantic analysis frameworks, or repository maintenance.

Read the focused references before an expert workflow:

1. api-reference for node families, dataclasses, enums, signatures, and version instability.
2. parsing-and-printing for parser modes, spans, comments, normalized output, and round trips.
3. visitors-and-transformers for dispatch, context, mutation, deletion, splicing, and safe rewrites.
4. troubleshooting when imports, generated parser files, versions, construction, or transformed output fail.

Install and smoke-test

The AST and printer are available from the openqasm3 package. Install the parser extra for parsing text:

python -m pip install 'openqasm3[parser]'

Confirm the runtime rather than assuming a remembered API:

import inspect
import openqasm3
from openqasm3 import ast, spec

print(openqasm3.__version__, spec.supported_versions)
print(inspect.signature(openqasm3.parse))
print(len(ast.__all__))

The current verified baseline is package version 1.0.1, with specification versions 3.0 and 3.1 supported by the parser. The AST API is explicitly unstable; if a signature or node field differs, use the installed runtime's introspection and then record the discrepancy.

Standard workflow

1. Acquire text safely. Read a file or an in-memory string. Do not treat comments as AST nodes; collect them separately if they matter.
2. Preflight the version. Call openqasm3.parse_version(text) when choosing a parser or diagnosing a source. It returns an integer tuple or None.
3. Parse strictly first. Call openqasm3.parse(text) with defaults. Use permissive=True only for exploratory recovery, and treat any recovered AST as potentially invalid. Use ignore_version=True only for deliberate compatibility experiments, never as proof of conformance.
4. Inspect or transform. Use dataclass fields and QASMVisitor/ QASMTransformer; do not assume a binding or semantic symbol table exists.
5. Print and validate. Use openqasm3.dumps(program, ...), then parse the result again. Compare AST structure after deliberately ignoring spans when testing formatting-only changes. A successful reparse proves grammar/parser acceptance, not semantic or provider validity.
6. Report boundaries. Separate normative language meaning, grammar acceptance, parser contextual checks, semantic/compiler validity, and provider execution in the result.

Smallest useful API map

• openqasm3.ast: dataclass AST nodes, enums, Span, and base classes.
• openqasm3.parse and openqasm3.parser.parse: text to ast.Program.
• openqasm3.parse_version: leading version probe.
• openqasm3.parser.get_comments: separate line/block comment extraction.
• openqasm3.dump/dumps: AST to normalized text.
• openqasm3.printer.Printer: configurable visitor-backed printer.
• openqasm3.visitor.QASMVisitor: read-only traversal base.
• openqasm3.visitor.QASMTransformer: in-place rewrite base.
• openqasm3.properties.precedence: expression precedence comparison only.

For repeatable inspection, use scripts/inspect_program.py. For a deliberately narrow rename demonstration, use scripts/rename_identifiers.py; it refuses obvious global collisions, reparses before success, and never silently replaces the input file.

Guardrails

• Constructors make structurally shaped nodes; they do not establish all language semantics or name binding.
• Parsed nodes normally have spans; newly constructed nodes normally do not. Spans are source metadata, not a concrete-syntax tree.
• Printing drops comments and normalizes whitespace/formatting. Preserve the original text separately when comments or exact formatting are requirements.
• A transformed AST can still be invalid, incomplete, or semantically wrong; always print/reparse and run the appropriate grammar/conformance and semantic checks owned by other workflows.