[](https://github.com/python-compiler-tools/ast-compat/blob/main/LICENSE)
[](https://pypi.org/project/ast-compat/#history)
[](https://pypi.org/project/ast-compat/)
# AST-Compat
Compatible AST construction and `ast.unparse` for Python 3.5-3.13.
## What is AST-Compat for?
- **backward compatibility for constructing ASTs**
For instance, `ast.arguments` is changed since Python 3.8, that another field `posonlyarg` is introduced,
hence you should construct an `ast.arguments` with an additional argument `posonlyarg=...` since Python 3.8
and it wouldn't work if your code is written before Python 3.8.
Through `ast_compat`, you don't have to worry about above question if a new argument is **optional or a list**.
**Note that you should use `ast_compat.XXX` instead of `ast.XXX` to construct ASTs.**
- Support **ast.Constant** before Python 3.6.
`ast.Constant` is convenient, and things like `ast.Num` are redundant according to this observation and improvement: https://bugs.python.org/issue32892
However, `ast.Constant` is not available in 3.5 or earlier versions, thus we backport `ast.Constant` in this library.
To access the content of `ast.Constant` in a compatible way, use `ast_compat.get_constant` instead of `.value`.
- Support dumping AST to string with **ast_compat.unparse**, which synchronizes the tooling code provided by CPython official repo.
## Usage
```python
import ast_compat as astc
from ast_compat import get_constant
assert get_constant(astc.Constant((1, 2))) == (1, 2)
empty_args = astc.arguments() # work for all of Python 3.5-3.13
```
## Implementation, and rebuild
The compatibility is following the specification of Python ASTs, i.e,
the ADSL file you can find at
`https://github.com/python/cpython/blob/<branch/tag>/Parser/Python.asdl`.
We parse the file, and generate verifications and default argument factories,
check `ast_compat/compat3k*_{ast|unparse}.py`. To explain, `ast_compat/compat3k5_*.py` is for
Python 3.5, and `ast_compat/compat3k9_*.py` is for Python 3.9.
The file of generator is `generate_ast_compat.py`, and the use of generator API is in this way:
```python
from generate_ast_compat import compat
compat((3, 5)) # generate ast_compat/compat3k5_ast.py and ast_compat/compat3k5_unparse.py
compat((3, 6))
compat((3, 7))
compat((3, 8))
prerelease_url = "https://raw.githubusercontent.com/python/cpython/v3.9.0a3/parser/python.asdl"
compat((3, 9), prerelease_url)
```
The code generation needs Python 3.7+, though this library works for Python 3.5 and 3.5+.
Raw data
{
"_id": null,
"home_page": "https://github.com/python-compiler-tools/ast-compat",
"name": "ast-compat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "ast compat",
"author": "thautwarm",
"author_email": "twshere@outlook.com",
"download_url": null,
"platform": "any",
"description": "[](https://github.com/python-compiler-tools/ast-compat/blob/main/LICENSE)\r\n[](https://pypi.org/project/ast-compat/#history)\r\n[](https://pypi.org/project/ast-compat/)\r\n\r\n# AST-Compat\r\n\r\nCompatible AST construction and `ast.unparse` for Python 3.5-3.13.\r\n\r\n## What is AST-Compat for?\r\n\r\n- **backward compatibility for constructing ASTs**\r\n\r\n For instance, `ast.arguments` is changed since Python 3.8, that another field `posonlyarg` is introduced,\r\n hence you should construct an `ast.arguments` with an additional argument `posonlyarg=...` since Python 3.8\r\n and it wouldn't work if your code is written before Python 3.8.\r\n\r\n Through `ast_compat`, you don't have to worry about above question if a new argument is **optional or a list**.\r\n\r\n **Note that you should use `ast_compat.XXX` instead of `ast.XXX` to construct ASTs.**\r\n\r\n- Support **ast.Constant** before Python 3.6.\r\n\r\n `ast.Constant` is convenient, and things like `ast.Num` are redundant according to this observation and improvement: https://bugs.python.org/issue32892\r\n\r\n However, `ast.Constant` is not available in 3.5 or earlier versions, thus we backport `ast.Constant` in this library.\r\n\r\n To access the content of `ast.Constant` in a compatible way, use `ast_compat.get_constant` instead of `.value`.\r\n\r\n- Support dumping AST to string with **ast_compat.unparse**, which synchronizes the tooling code provided by CPython official repo.\r\n\r\n## Usage\r\n\r\n```python\r\nimport ast_compat as astc\r\nfrom ast_compat import get_constant\r\n\r\nassert get_constant(astc.Constant((1, 2))) == (1, 2)\r\n\r\nempty_args = astc.arguments() # work for all of Python 3.5-3.13\r\n```\r\n\r\n\r\n## Implementation, and rebuild\r\n\r\nThe compatibility is following the specification of Python ASTs, i.e,\r\nthe ADSL file you can find at\r\n\r\n`https://github.com/python/cpython/blob/<branch/tag>/Parser/Python.asdl`.\r\n\r\nWe parse the file, and generate verifications and default argument factories,\r\ncheck `ast_compat/compat3k*_{ast|unparse}.py`. To explain, `ast_compat/compat3k5_*.py` is for\r\nPython 3.5, and `ast_compat/compat3k9_*.py` is for Python 3.9.\r\n\r\nThe file of generator is `generate_ast_compat.py`, and the use of generator API is in this way:\r\n\r\n```python\r\nfrom generate_ast_compat import compat\r\ncompat((3, 5)) # generate ast_compat/compat3k5_ast.py and ast_compat/compat3k5_unparse.py\r\ncompat((3, 6))\r\ncompat((3, 7))\r\ncompat((3, 8))\r\nprerelease_url = \"https://raw.githubusercontent.com/python/cpython/v3.9.0a3/parser/python.asdl\"\r\ncompat((3, 9), prerelease_url)\r\n```\r\n\r\nThe code generation needs Python 3.7+, though this library works for Python 3.5 and 3.5+.\r\n",
"bugtrack_url": null,
"license": "mit",
"summary": "cross-version compatible ast library",
"version": "0.12.0",
"project_urls": {
"Homepage": "https://github.com/python-compiler-tools/ast-compat"
},
"split_keywords": [
"ast",
"compat"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5d006e348161072f45b610d80427196ee249a030783179f5d65473983c15b76",
"md5": "053c3a27dfa12dcf80f124c6e6f2a321",
"sha256": "911d81236a18201d4930c93ccd6a2d3dd14442cbccfbd2787b883ac8cb38b208"
},
"downloads": -1,
"filename": "ast_compat-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "053c3a27dfa12dcf80f124c6e6f2a321",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 53143,
"upload_time": "2024-09-17T05:38:00",
"upload_time_iso_8601": "2024-09-17T05:38:00.551557Z",
"url": "https://files.pythonhosted.org/packages/d5/d0/06e348161072f45b610d80427196ee249a030783179f5d65473983c15b76/ast_compat-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-17 05:38:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "python-compiler-tools",
"github_project": "ast-compat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ast-compat"
}
JSON
