RedBaron Documentation

RedBaron nodes are highly flexible when setting attributes. You can assign values using several different formats, and RedBaron will adapt accordingly:

1. String: The string is parsed as Python code and converted into RedBaron nodes.
2. FST Data (Dictionary): Passing a raw FST (Full Syntax Tree) dictionary will transform that data into a RedBaron object.
3. RedBaron Node/List: You can pass existing node instances or lists of nodes directly.
4. Mixed Content: For list attributes, you can mix FST dictionaries, strings, and existing nodes; RedBaron will parse/transform each element based on its type.

from redbaron import RedBaron

red = RedBaron("a = b")

# 1. Data attribute (no parsing, just sets value)
red.name.value = "something_else"

# 2. Node attribute with a string (triggers parsing)
red[0].value = "42 * pouet"

# 3. Node attribute with FST data (transforms to RedBaron object)
red[0].value = {"type": "name", "value": "pouet"}

# 4. List attribute with mixed content
red_list = RedBaron("[1, 2, 3]")
red_list[0].value = [
    {"type": "name", "value": "pouet"}, # FST dict
    "pouet ,",                               # String (parsed)
    NameNode({"type": "name", "value": "plop"}) # Existing Node
]

Standard .next and .previous navigation follows the Full Syntax Tree (FST), which might not match human expectations for control structures. For example, .next on a TryNode returns the node after the entire try-except-else-finally block, rather than the first ExceptNode.

To navigate logically through control structures like TryNode, IfNode, ElifNode, ElseNode, ForNode, and WhileNode, use .next_intuitive() and .previous_intuitive().

Note on IfelseblockNode:

• .next_intuitive() on an IfNode or ElifNode inside an IfelseblockNode will move to the next branch within that block.
• Calling .next_intuitive() on the IfelseblockNode itself will jump to the first/last node inside the block.

red = RedBaron("try:\n    pass\nexcept:\n    pass\nafter")
# Standard navigation jumps over the whole block
red.try_.next 

# Intuitive navigation moves to the except block
red.try_.next_intuitive

RedBaron allows you to navigate the AST using BeautifulSoup-style queries and modify nodes by assigning new Python code (as strings) to their attributes.

Querying

Use .find() to locate a single node or .find_all() (or the shorthand ()) to find all matching nodes. Queries can use values, lambdas, regex, or globs.

Modifying

To change a node, assign a string containing the new code to the desired attribute (e.g., .value).

Extending Source

RedBaron objects support list-like operations such as .extend() to append new lines or code blocks to the existing source.

from redbaron import RedBaron

red = RedBaron("some_value = 42")

# Querying: find an integer node with value 4
# red.find("int", value=4)

# Modifying: change the value of the first node
red[0].value = "1 + 4"

# Extending: add new lines of code
red.extend(["\n", "INSTALLED_APPS = []"])

# Complex query and modification
# Find an assignment where the target is 'INSTALLED_APPS' and append to its value
red.find("assignment", target=lambda x: x.dumps() == "INSTALLED_APPS").value.append("'django'")

print(red.dumps())

RedBaron uses a Full Syntax Tree (FST) to represent Python code. Unlike the standard ast module, which removes formatting and certain structural details, an FST preserves the exact representation of your code, including its formatting.

This makes RedBaron suitable for complex code manipulation tasks where you need to modify code and convert it back to a string without losing the original style or accidentally affecting non-target elements (like text inside strings).

Use RedBaron when you need to perform:

• Variable renaming without clashing with string literals.
• Inlining functions or methods.
• Extracting functions/methods from specific lines of code.
• Splitting classes or files into new modules/classes.
• Large-scale refactoring (e.g., converting ORMs).
• Custom refactoring operations not supported by standard IDEs.
• Code generation and deep code analysis that requires structural fidelity.

RedBaron provides four specialized proxy list types depending on the structure you are modifying:

1. CommaProxyList: Used for comma-separated lists (e.g., [1, 2, 3]). This is the most common type.
2. DotProxyList: Used for dot-separated sequences (atomtrailers) like a.b[plop].c(). It is intelligent enough to handle calls () and indexing [] without incorrectly adding extra dots.
3. LineProxyList: Used for lines of code (e.g., function bodies or entire files). It manages end-of-line nodes and indentation automatically. It explicitly represents empty lines so you can manage spacing.
4. DecoratorLineProxyList: Similar to LineProxyList but specifically handles the indentation of decorators. Note: You must include the @ symbol when appending a new decorator.

# DotProxyList example
red = RedBaron("a.b(c).d[e]")
red[0].value.extend(["[stuff]", "f", "(g, h)"])

# DecoratorLineProxyList example
red = RedBaron("@plop\ndef stuff():\n    pass\n")
red[0].decorators.append("@plouf")