{"id":9497,"library":"astcheck","title":"astcheck - Check Python ASTs against templates","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/takluyver/astcheck","tags":["ast","abstract syntax tree","testing","static analysis","code analysis"],"install":[{"cmd":"pip install astcheck","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"is_ast_match","correct":"from astcheck import is_ast_match"},{"symbol":"assert_ast_equal","correct":"from astcheck import assert_ast_equal"},{"note":"Used to extract specific nodes or values that match placeholders in a template.","symbol":"match_ast","correct":"from astcheck import match_ast"},{"note":"A placeholder for any identifier in a template AST.","symbol":"NAME","correct":"from astcheck import NAME"}],"quickstart":{"code":"import ast\nfrom astcheck import is_ast_match, assert_ast_equal, NAME\n\n# The target AST node to check\ncode_to_check = \"\"\"x = 1 + y\"\"\"\nnode = ast.parse(code_to_check)\n\n# Define a template AST using ast.parse() and astcheck placeholders\ntemplate = ast.parse(\"\"\"some_var = 1 + another_var\"\"\")\n\n# Using is_ast_match to check if the target AST matches the template structure\nis_match = is_ast_match(node, template, some_var=NAME, another_var=NAME)\nassert is_match, \"The AST structure should match the template!\"\n\nprint(f\"AST '{code_to_check.strip()}' matches template: {is_match}\")\n\n# Using assert_ast_equal for a stricter comparison (all non-placeholder nodes must be identical)\n# For exact matching, often you wouldn't use NAME placeholders\nstrict_template = ast.parse(\"\"\"x = 1 + y\"\"\")\nassert_ast_equal(node, strict_template)\nprint(\"Strict AST comparison successful.\")\n\n# Example with extracted matches (if using match_ast instead of is_ast_match)\nfrom astcheck import match_ast, N_INT\nmatch_result = match_ast(node, ast.parse(\"var_name = LITERAL + OTHER_VAR\"), var_name=NAME, LITERAL=N_INT, OTHER_VAR=NAME)\nassert match_result is not None\nprint(f\"Extracted variable name: {match_result['var_name'].id}\")\nprint(f\"Extracted literal value: {match_result['LITERAL'].value}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Always use `ast.parse('your_code_string')` to convert your template string into an AST node before passing it to `astcheck` functions.","message":"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`.","severity":"gotcha","affected_versions":"0.1.0-0.4.0"},{"fix":"Ensure you `from astcheck import NAME, N_INT, ...` and then pass `some_name=NAME` or use `astcheck.NAME` in your template where appropriate.","message":"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`).","severity":"gotcha","affected_versions":"0.1.0-0.4.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"0.1.0-0.4.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Use `import ast` and `ast.parse('your code here')` to convert your code strings into AST nodes before passing them to `astcheck`.","cause":"Attempting to pass a raw Python code string as a template or target AST to `is_ast_match` or `assert_ast_equal`.","error":"TypeError: expected ast.AST, got <class 'str'>"},{"fix":"Add `from astcheck import is_ast_match, assert_ast_equal, NAME` (or other necessary symbols) at the top of your script.","cause":"Forgetting to import the required `astcheck` functions or placeholders.","error":"NameError: name 'is_ast_match' is not defined"},{"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.","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.","error":"AssertionError (from assert_ast_equal or a failed assert is_ast_match)"}]}