# OpenQASM 3 Python Reference
[](https://opensource.org/licenses/Apache-2.0)<!-- long-description-skip-begin -->[](https://pypi.org/project/openqasm3)<!-- long-description-skip-end -->
The `openqasm3` package 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, and _no_ parts 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.
## Installation
The package can be installed from PyPI (`pip`) with the command
```bash
python -m pip install openqasm3
```
If you want to use the parser, you will need to install the extra `parsing`, and to run the tests you need the extra `tests`, for example `pip install openqasm3[tests]`.
All extras can be installed with the target `openqasm3[all]`.
## Development Environment
To work on development, you will need to have a complete [ANTLR](https://www.antlr.org/) installation (not just the runtime), and the ANTLR grammar files from the [main OpenQASM repository](https://github.com/Qiskit/openqasm).
### Setting up ANTLR
You can most likely get a copy of ANTLR using your system package manager if you are on Linux, or from [Homebrew](https://brew.sh) (`brew`) on macOS.
Otherwise, you can follow [these instructions](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md).
Make a note of the version of ANTLR you have installed, because you will need to ensure your version of `antlr4-python3-runtime` matches up to the minor version.
Once you have ANTLR installed, change to the directory where the `qasm3*.g4` files are located (for example, `repo_root/source/grammar`), and run
```bash
<antlr command> -o <path to here>/openqasm3/_antlr/_<major>_<minor> -Dlanguage=Python3 -visitor qasm3Lexer.g4 qasm3Parser.g4
```
For example, if this repository is cloned to `~/openqasm` and the command to run ANTLR 4.11.1 is `antlr4`, then you should run
```bash
cd ~/openqasm/source/grammar
antlr4 -o ~/openqasm/source/openqasm/openqasm3/_antlr/_4_11 -Dlanguage=Python3 -visitor qasm3Lexer.g4 qasm3Parser.g4
```
You 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 of `antlr4_python3_runtime` when it is imported.
### Developer tools
Install the rest of the Python development environment with
```bash
python -m pip install -r requirements.txt -r requirements-dev.txt
```
ensuring that the version of `antlr4-python3-runtime` exactly matches the version of ANTLR you have.
Install the Python package in editable mode with
```bash
python -m pip install -e .
```
The project is configured to use the code formatter [`black`](https://pypi.org/project/black), linter [`pylint`](https://pylint.org) and tester [`pytest`](https://pytest.org).
The commands to run these are, respectively:
```bash
black .
pylint .
pytest
```
### Deployment procedure
The deployment is primarily managed by a GitHub Actions pipeline, triggered by a tag of the form `ast-py/v<version>`.
For example, for package version `0.4.0`, the tag should be `ast-py/v0.4.0`.
To deploy:
1. create a PR that sets the version number of the package in `__init__.py` and `docs/conf.py` to what it should be.
2. 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`).
3. 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 progress [in the Actions tab of this repository](https://github.com/openqasm/openqasm/actions/workflows/deploy-ast.yml).
Raw data
{
"_id": null,
"home_page": "https://github.com/Qiskit/openqasm",
"name": "openqasm3",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "openqasm quantum",
"author": "OpenQASM Contributors",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/c7/f1/c63ef1778a387a3377f2a9ca6be497303745ee634e5b9f3cfd0776f40d76/openqasm3-0.5.0.tar.gz",
"platform": null,
"description": "# OpenQASM 3 Python Reference\n\n[](https://opensource.org/licenses/Apache-2.0)<!-- long-description-skip-begin -->[](https://pypi.org/project/openqasm3)<!-- long-description-skip-end -->\n\nThe `openqasm3` package 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.\n\nThe AST is intended to help with writing compiler passes for OpenQASM 3 in Python.\nIt aims to have no dependencies for users who consume the Python tree structure, and minimal dependencies for parsing a string to this tree structure.\nThe AST is simpler than a Concrete Syntax Tree (CST) which preserves comments, spacing, etc for use by editor plugins.\n\nThe package consists of the modules:\n\n* `openqasm3.ast`: The AST nodes.\n\n* `openqasm3.parser`:\n A parser based on an ANTLR grammar and reference parser also found in this repo.\n It walks the ANTLR parse tree to generate the AST.\n\n* `openqasm3.visitor`: A base AST visitor and transformer.\n\n* `tests`: A set of unit tests.\n\n\n**Note**: this reference Python package is currently in the early stages of development, and _no_ parts of the API should be considered stable at this time.\nThe AST itself will be subject to change in backwards-incompatible ways, mirroring the development of the OpenQASM 3 languge itself.\n\n\n## Installation\n\nThe package can be installed from PyPI (`pip`) with the command\n\n```bash\npython -m pip install openqasm3\n```\n\nIf you want to use the parser, you will need to install the extra `parsing`, and to run the tests you need the extra `tests`, for example `pip install openqasm3[tests]`.\nAll extras can be installed with the target `openqasm3[all]`.\n\n\n## Development Environment\n\nTo work on development, you will need to have a complete [ANTLR](https://www.antlr.org/) installation (not just the runtime), and the ANTLR grammar files from the [main OpenQASM repository](https://github.com/Qiskit/openqasm).\n\n### Setting up ANTLR\n\nYou can most likely get a copy of ANTLR using your system package manager if you are on Linux, or from [Homebrew](https://brew.sh) (`brew`) on macOS.\nOtherwise, you can follow [these instructions](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md).\nMake a note of the version of ANTLR you have installed, because you will need to ensure your version of `antlr4-python3-runtime` matches up to the minor version.\n\nOnce you have ANTLR installed, change to the directory where the `qasm3*.g4` files are located (for example, `repo_root/source/grammar`), and run\n```bash\n<antlr command> -o <path to here>/openqasm3/_antlr/_<major>_<minor> -Dlanguage=Python3 -visitor qasm3Lexer.g4 qasm3Parser.g4\n```\n\nFor example, if this repository is cloned to `~/openqasm` and the command to run ANTLR 4.11.1 is `antlr4`, then you should run\n```bash\ncd ~/openqasm/source/grammar\nantlr4 -o ~/openqasm/source/openqasm/openqasm3/_antlr/_4_11 -Dlanguage=Python3 -visitor qasm3Lexer.g4 qasm3Parser.g4\n```\n\nYou can install more than one version of the ANTLR files at once, provided you put them in the correct version directories.\nThe package will dynamically choose the correct version based on the installed version of `antlr4_python3_runtime` when it is imported.\n\n### Developer tools\n\nInstall the rest of the Python development environment with\n```bash\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\nensuring that the version of `antlr4-python3-runtime` exactly matches the version of ANTLR you have.\n\nInstall the Python package in editable mode with\n```bash\npython -m pip install -e .\n```\n\nThe project is configured to use the code formatter [`black`](https://pypi.org/project/black), linter [`pylint`](https://pylint.org) and tester [`pytest`](https://pytest.org).\nThe commands to run these are, respectively:\n```bash\nblack .\npylint .\npytest\n```\n\n\n### Deployment procedure\n\nThe deployment is primarily managed by a GitHub Actions pipeline, triggered by a tag of the form `ast-py/v<version>`.\nFor example, for package version `0.4.0`, the tag should be `ast-py/v0.4.0`.\n\nTo deploy:\n\n1. create a PR that sets the version number of the package in `__init__.py` and `docs/conf.py` to what it should be.\n2. 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`).\n3. push the tag to this repository (for example, `git push origin ast-py/v0.4.0`).\n\nAt this point, the deployment pipeline will take over and deploy the package to PyPI.\nYou should be able to see the progress [in the Actions tab of this repository](https://github.com/openqasm/openqasm/actions/workflows/deploy-ast.yml).\n",
"bugtrack_url": null,
"license": "Apache 2.0 Software License",
"summary": "Reference OpenQASM AST in Python",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/Qiskit/openqasm"
},
"split_keywords": [
"openqasm",
"quantum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5191574addbe722736081d1b9c78212f8cac5e9d93c8bc79059c84871034c527",
"md5": "c3e03f91229601e21a1ab207aebd3f05",
"sha256": "40991ac057b9e3c208d1b34242b0aad8a3b9840df0335a652b1e4e4248937b1c"
},
"downloads": -1,
"filename": "openqasm3-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3e03f91229601e21a1ab207aebd3f05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 524019,
"upload_time": "2023-06-19T23:31:44",
"upload_time_iso_8601": "2023-06-19T23:31:44.897012Z",
"url": "https://files.pythonhosted.org/packages/51/91/574addbe722736081d1b9c78212f8cac5e9d93c8bc79059c84871034c527/openqasm3-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7f1c63ef1778a387a3377f2a9ca6be497303745ee634e5b9f3cfd0776f40d76",
"md5": "4d9098c513d0c881e174eb04c263b7c5",
"sha256": "bf8bf4ed098393447e552eaea18b0a34a2429d228477683d6b579348bc17bfc8"
},
"downloads": -1,
"filename": "openqasm3-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "4d9098c513d0c881e174eb04c263b7c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 517167,
"upload_time": "2023-06-19T23:31:46",
"upload_time_iso_8601": "2023-06-19T23:31:46.567476Z",
"url": "https://files.pythonhosted.org/packages/c7/f1/c63ef1778a387a3377f2a9ca6be497303745ee634e5b9f3cfd0776f40d76/openqasm3-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 23:31:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Qiskit",
"github_project": "openqasm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "openqasm3"
}
JSON
