AST Trouble Spots: Handling ast.FormattedValue and ast.Interpolation in Python

The ast.Interpolation node is specifically part of how modern Python handles f-strings (formatted string literals), which were introduced in Python 3.6. It represents a single expression within the curly braces {} inside an f-string.

However, I need to point out something crucial based on the official documentation

For Python versions up to 3.13, the structure for f-strings uses ast.JoinedStr (the whole f-string) which contains a list of ast.Constant (the static text parts) and ast.FormattedValue (the expressions within {}). The name you mentioned, ast.Interpolation, does not exist in these versions.

For Python 3.14 (and later), the AST has been revised to better support template strings (including f-strings). In this new structure, f-strings are often represented by ast.TemplateStr nodes, and the parts that contain expressions are indeed represented by the ast.Interpolation node (or sometimes within ast.FormattedValue within an ast.JoinedStr if it's being unparsed/processed from an older AST format).

Since the documentation snippets suggest ast.Interpolation is related to new features and possibly an internal node or a transitional one, I'll focus the explanation on the widely used ast.FormattedValue (for current Python versions) and also address the ast.Interpolation context. Both represent the same core concept
a value interpolated into a string.

Here's a friendly breakdown of this concept, common challenges, and alternative approaches!

When you write an f-string like f"Hello, {name}!", the Python compiler first parses this into an Abstract Syntax Tree (AST). The expression inside the {} is the "interpolation."

This is the node class you'll most commonly encounter when dealing with f-strings in Python versions up to at least 3.13.

This node appears in the newer template string AST structure (Python 3.14+). It generally contains very similar information but is designed to work with ast.TemplateStr. The key difference is that it often includes a str field which is the raw source of the interpolated expression, which helps during unparsing.

Working with these nodes usually involves analyzing or modifying the code represented by the AST.

When you modify the value of an interpolation node (FormattedValue or Interpolation) and then use a utility like ast.unparse() to convert the AST back into code, you might find that the original source code is still generated!

Why? The newer ast.Interpolation node often has a str field, which holds the original source code of the expression (e.g., if you wrote {x+1}, the value is an ast.BinOp, but str is the string 'x+1'). The ast.unparse() function sometimes prioritizes this str field over the actual value node for simplicity, especially for f-strings/template strings.

If you change the logic (value) but don't update the raw string (str), the unparser will ignore your change. You need to use ast.unparse() on the new value to generate the new source code for the str field!

import ast
from ast import unparse

code = 'f"The result is {a + b}!"'
tree = ast.parse(code)

# Visitor/Transformer to find and modify the Interpolation (FormattedValue)
class InterpolationChanger(ast.NodeTransformer):
    def visit_FormattedValue(self, node):
        # 1. Create a NEW expression node, e.g., change 'a + b' to 'a * b'
        new_value = ast.BinOp(
            left=ast.Name(id='a', ctx=ast.Load()),
            op=ast.Mult(),
            right=ast.Name(id='b', ctx=ast.Load())
        )
        
        # 2. Update the 'value'
        node.value = new_value
        
        # 3. CRITICAL: For unparsing consistency, you should also update 
        #    the raw 'str' field if you were using ast.Interpolation 
        #    (though FormattedValue doesn't have it).
        #    If you *were* using ast.Interpolation (Python 3.14+):
        #    node.str = unparse(new_value) 
        
        # Always call the generic visitor for children
        return self.generic_visit(node)

# Apply the transformation
new_tree = InterpolationChanger().visit(tree)
new_code = unparse(new_tree)

print(f"Original: {code}")
print(f"Modified: {new_code}")

# Output (for FormattedValue in modern Python):
# Original: f"The result is {a + b}!"
# Modified: f"The result is {a * b}!"
# (The FormattedValue node is typically well-handled by unparse 
# without needing to explicitly set a 'str' field.)

Since working directly with the AST is complex, most programmers use simpler, high-level methods for string formatting unless they are building a code analyzer, linter, or metaprogramming tool.

If your goal is to change the expression itself, and you can rewrite the source code rather than manipulating the AST directly, using the .format() method might offer a simpler structure in the AST if you are trying to analyze a fixed string and simple arguments.

# Instead of AST modification, just rewrite the code using .format()
original_code = 'print(f"Value: {x + 1}")'

# If you were rewriting the source:
alternative_code = 'print("Value: {}".format(x * 2))'

# When you parse the alternative_code:
# ast.parse(alternative_code) 
# -> Will result in ast.Call (for print) containing an ast.Call (for .format)
#    which has simpler arguments (Name, BinOp) than the nested structure of f-strings.
#    This can sometimes be easier to analyze/modify if you're not specifically 
#    targeting f-string features.

print(f"Rewritten Code (Functional Alternative): {alternative_code}")