Package: openqasm3
OpenQASM 3 Python ReferenceTheopenqasm3package contains the reference abstract syntax tree (AST) for representing OpenQASM 3 programs, tools to parse text into this AST, and tools to manipulate the AST.The AST is intended to help with writing compiler passes for OpenQASM 3 in Python.
It aims to have no dependencies for users who consume the Python tree structure, and minimal dependencies for parsing a string to this tree structure.
The AST is simpler than a Concrete Syntax Tree (CST) which preserves comments, spacing, etc for use by editor plugins.The package consists of the modules:openqasm3.ast: The AST nodes.openqasm3.parser:
A parser based on an ANTLR grammar and reference parser also found in this repo.
It walks the ANTLR parse tree to generate the AST.openqasm3.visitor: A base AST visitor and transformer.tests: A set of unit tests.Note: this reference Python package is currently in the early stages of development, andnoparts of the API should be considered stable at this time.
The AST itself will be subject to change in backwards-incompatible ways, mirroring the development of the OpenQASM 3 languge itself.InstallationThe package can be installed from PyPI (pip) with the commandpython-mpipinstallopenqasm3If you want to use the parser, you will need to install the extraparsing, and to run the tests you need the extratests, for examplepip install openqasm3[tests].
All extras can be installed with the targetopenqasm3[all].Development EnvironmentTo work on development, you will need to have a completeANTLRinstallation (not just the runtime), and the ANTLR grammar files from themain OpenQASM repository.Setting up ANTLRYou can most likely get a copy of ANTLR using your system package manager if you are on Linux, or fromHomebrew(brew) on macOS.
Otherwise, you can followthese instructions.
Make a note of the version of ANTLR you have installed, because you will need to ensure your version ofantlr4-python3-runtimematches up to the minor version.Once you have ANTLR installed, change to the directory where theqasm3*.g4files are located (for example,repo_root/source/grammar), and run<antlrcommand>-o<pathtohere>/openqasm3/_antlr/_<major>_<minor>-Dlanguage=Python3-visitorqasm3Lexer.g4qasm3Parser.g4For example, if this repository is cloned to~/openqasmand the command to run ANTLR 4.11.1 isantlr4, then you should runcd~/openqasm/source/grammar
antlr4-o~/openqasm/source/openqasm/openqasm3/_antlr/_4_11-Dlanguage=Python3-visitorqasm3Lexer.g4qasm3Parser.g4You can install more than one version of the ANTLR files at once, provided you put them in the correct version directories.
The package will dynamically choose the correct version based on the installed version ofantlr4_python3_runtimewhen it is imported.Developer toolsInstall the rest of the Python development environment withpython-mpipinstall-rrequirements.txt-rrequirements-dev.txtensuring that the version ofantlr4-python3-runtimeexactly matches the version of ANTLR you have.Install the Python package in editable mode withpython-mpipinstall-e.The project is configured to use the code formatterblack, linterpylintand testerpytest.
The commands to run these are, respectively:black.
pylint.
pytestDeployment procedureThe deployment is primarily managed by a GitHub Actions pipeline, triggered by a tag of the formast-py/v<version>.
For example, for package version0.4.0, the tag should beast-py/v0.4.0.To deploy:create a PR that sets the version number of the package in__init__.pyanddocs/conf.pyto what it should be.once the PR has merged, tag the merge commit (for example,git fetch origin; git tag -m "Python AST 0.4.0" ast-py/v0.4.0 origin/main).push the tag to this repository (for example,git push origin ast-py/v0.4.0).At this point, the deployment pipeline will take over and deploy the package to PyPI.
You should be able to see the progressin the Actions tab of this repository.