Moving Symbols

Codegen provides fast, configurable and safe APIs for moving symbols (functions, classes, variables) between files while automatically handling imports and dependencies.

The key API is Symbol.move_to_file(…).

Basic Symbol Movement

Simply call Symbol.move_to_file(…) to move a symbol to a new file.

# Manipulation code:
file1 = codebase.get_file("file1.py")
file2 = codebase.get_file("file2.py")

helper_func = file1.get_symbol("helper")

# Ensure the destination file exists
if not file2.exists():
    file2 = codebase.create_file('file2.py')

# Move the symbol
helper_func.move_to_file(file2)

By default, this will move any dependencies, including imports, to the new file.

Moving Strategies

The Symbol.move_to_file(…) method accepts a strategy parameter, which can be used to control how imports are updated.

Your options are:

• "update_all_imports": Updates all import statements across the codebase (default)
• "add_back_edge": Adds import and re-export in the original file

"add_back_edge" is useful when moving a symbol that is depended on by other symbols in the original file, and will result in smaller diffs.

"add_back_edge" will result in circular dependencies if the symbol has non-import dependencies in it’s original file.

Moving Symbols in Bulk

Make sure to call Codebase.commit(…) after moving symbols in bulk for performant symbol movement.

# Move all functions with a specific prefix
for file in codebase.files:
    for function in file.functions:
        if function.name.startswith("pylsp_"):
            function.move_to_file(
                shared_file,
                include_dependencies=True,
                strategy="update_all_imports"
            )

# Commit the changes once, at the end
codebase.commit()