astcheck - Check Python ASTs against templates

Common errors

• TypeError: expected ast.AST, got <class 'str'>

  cause Attempting to pass a raw Python code string as a template or target AST to `is_ast_match` or `assert_ast_equal`.
  fix Use `import ast` and `ast.parse('your code here')` to convert your code strings into AST nodes before passing them to `astcheck`.

• NameError: name 'is_ast_match' is not defined

  cause Forgetting to import the required `astcheck` functions or placeholders.
  fix Add `from astcheck import is_ast_match, assert_ast_equal, NAME` (or other necessary symbols) at the top of your script.

• AssertionError (from assert_ast_equal or a failed assert is_ast_match)

  cause The target AST node does not structurally match the provided template AST node, or the specific values/types expected by the template are not present.
  fix Use `print(ast.dump(target_node))` and `print(ast.dump(template_node))` to inspect the exact AST structures. Pay close attention to node types (e.g., `ast.Constant` vs `ast.Name`), values, and attribute names.

Warnings

• gotcha Templates 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.
• gotcha Placeholders 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.
• gotcha AST 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.

Install

• pip install astcheck Install stable version

Imports

• is_ast_match

  from astcheck import is_ast_match

• assert_ast_equal

  from astcheck import assert_ast_equal

• match_ast

  from astcheck import match_ast

  Used to extract specific nodes or values that match placeholders in a template.
• NAME

  from astcheck import NAME

  A placeholder for any identifier in a template AST.

Quickstart

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}")