Registry / testing / astcheck

astcheck

JSON →
library0.4.0pypypi✓ verified 83d ago

astcheck is a Python library designed to check Abstract Syntax Trees (ASTs) against structured templates. It's particularly useful for testing AST transformations, linters, or any code that processes Python ASTs. The current version is 0.4.0, with releases occurring periodically to address minor improvements and Python version compatibility.

pip install astcheck
INSTALL
IMPORT
SIG · ASTCHECK
A
astcheck
testingpythonv0.4.0
Install
1.5s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

is_ast_like
from astcheck import is_ast_like
from astcheck import is_ast_match
assert_ast_like
from astcheck import assert_ast_like
ASTMismatch
from astcheck import ASTMismatch

This quickstart demonstrates how to parse Python code into an AST, define a template AST using `ast.parse` and `astcheck.NAME` placeholders, and then use `is_ast_match` to check for structural similarity. It also shows `assert_ast_equal` for strict comparisons and `match_ast` for extracting matched nodes.

import ast from astcheck import is_ast_match, assert_ast_equal, NAME # The target AST node to check code_to_check = """x = 1 + y""" node = ast.parse(code_to_check) # Define a template AST using ast.parse() and astcheck placeholders template = ast.parse("""some_var = 1 + another_var""") # Using is_ast_match to check if the target AST matches the template structure is_match = is_ast_match(node, template, some_var=NAME, another_var=NAME) assert is_match, "The AST structure should match the template!" print(f"AST '{code_to_check.strip()}' matches template: {is_match}") # Using assert_ast_equal for a stricter comparison (all non-placeholder nodes must be identical) # For exact matching, often you wouldn't use NAME placeholders strict_template = ast.parse("""x = 1 + y""") assert_ast_equal(node, strict_template) print("Strict AST comparison successful.") # Example with extracted matches (if using match_ast instead of is_ast_match) from astcheck import match_ast, N_INT match_result = match_ast(node, ast.parse("var_name = LITERAL + OTHER_VAR"), var_name=NAME, LITERAL=N_INT, OTHER_VAR=NAME) assert match_result is not None print(f"Extracted variable name: {match_result['var_name'].id}") print(f"Extracted literal value: {match_result['LITERAL'].value}")
Debug
Known issues
gotchaTemplates for `astcheck` functions must be actual AST nodes, not raw Python code strings. If you pass a string directly, you'll get a `TypeError`.
fix
Always use `ast.parse('your_code_string')` to convert your template string into an AST node before passing it to `astcheck` functions.
affects: 0.1.0-0.4.0
gotchaPlaceholders like `NAME`, `N_INT`, `N_STR`, etc., must be explicitly imported from `astcheck` and correctly assigned in the `kwargs` of matching functions or used directly in the template AST (e.g., `astcheck.NAME`).
fix
Ensure you `from astcheck import NAME, N_INT, ...` and then pass `some_name=NAME` or use `astcheck.NAME` in your template where appropriate.
affects: 0.1.0-0.4.0
gotchaAST comparison is structural, not textual. Differences in whitespace, comments, or explicit parentheses that do not alter the underlying AST structure will be ignored by `ast.parse` and thus by `astcheck`.
fix
If you need to debug why two ASTs are considered different, use `ast.dump(node)` for both the target and template ASTs to visualize their exact structure and identify discrepancies.
affects: 0.1.0-0.4.0
Upgrade
Version history
0.4.0latest on PyPI · released Jan 29, 2024
Audit
Dependencies

No dependency data recorded yet.

Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
astcheck — pip install astcheck · libregistry