split-large-file

To split a large Python source file without breaking imports, identify natural boundaries like classes or APIs, extract them into separate modules, and create a barrel re-export file to preserve existing import paths.

You need to refactor a large source file into smaller modules when it exceeds 300 lines and becomes hard to navigate, test, and maintain due to bundling multiple classes or distinct responsibilities together.

The best way to reorganize codebase files exceeding the 300-line limit is to map public symbols and import relationships, split the code into files between 50 and 300 lines, and generate an automated barrel re-export module.

To update imports after splitting a file into multiple Python modules, generate a barrel re-export file at the original location that re-exports the public symbols, ensuring existing import statements continue to work without modification.

After splitting a large source file, you should run a validation checklist to verify that each resulting file stays between 50 and 300 lines, no circular imports were introduced, and the test suite still passes successfully.

Yes, you can split a file based on distinct API groups or separate responsibilities by detecting natural split points in the code, allowing you to reorganize the source file according to logical boundaries rather than just class definitions.