diff options
| author | Batuhan Taskaya <isidentical@gmail.com> | 2024-05-22 01:39:26 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-05-22 01:39:26 (GMT) |
| commit | d065edfb66470bbf06367b3570661d0346aa6707 (patch) | |
| tree | b05bef2dcc06a4302a6e63627b36c5c90b2b6f0e /Doc | |
| parent | 0e3c8cda1f04c983994e76aea93600dbb4714832 (diff) | |
| download | cpython-d065edfb66470bbf06367b3570661d0346aa6707.zip cpython-d065edfb66470bbf06367b3570661d0346aa6707.tar.gz cpython-d065edfb66470bbf06367b3570661d0346aa6707.tar.bz2 | |
gh-60191: Implement ast.compare (#19211)
* bpo-15987: Implement ast.compare
Add a compare() function that compares two ASTs for structural equality. There are two set of attributes on AST node objects, fields and attributes. The fields are always compared, since they represent the actual structure of the code. The attributes can be optionally be included in the comparison. Attributes capture things like line numbers of column offsets, so comparing them involves test whether the layout of the program text is the same. Since whitespace seems inessential for comparing ASTs, the default is to compare fields but not attributes.
ASTs are just Python objects that can be modified in arbitrary ways. The API for ASTs is under-specified in the presence of user modifications to objects. The comparison respects modifications to fields and attributes, and to _fields and _attributes attributes. A user could create obviously malformed objects, and the code will probably fail with an AttributeError when that happens. (For example, adding "spam" to _fields but not adding a "spam" attribute to the object.)
Co-authored-by: Jeremy Hylton <jeremy@alum.mit.edu>
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/ast.rst | 14 | ||||
| -rw-r--r-- | Doc/whatsnew/3.14.rst | 7 |
2 files changed, 21 insertions, 0 deletions
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index d4ccf28..9ee56b9 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -2472,6 +2472,20 @@ effects on the compilation of a program: .. versionadded:: 3.8 +.. function:: compare(a, b, /, *, compare_attributes=False) + + Recursively compares two ASTs. + + *compare_attributes* affects whether AST attributes are considered + in the comparison. If *compare_attributes* is ``False`` (default), then + attributes are ignored. Otherwise they must all be equal. This + option is useful to check whether the ASTs are structurally equal but + differ in whitespace or similar details. Attributes include line numbers + and column offsets. + + .. versionadded:: 3.14 + + .. _ast-cli: Command-Line Usage diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 27c985b..39172ac 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -86,6 +86,13 @@ New Modules Improved Modules ================ +ast +--- + +Added :func:`ast.compare` for comparing two ASTs. +(Contributed by Batuhan Taskaya and Jeremy Hylton in :issue:`15987`) + + Optimizations ============= |