manasplice 0.1.0.3a0

Split top-level Python functions into dedicated modules and rewire imports automatically.

ManaSplice

ManaSplice is a small CLI for pulling top-level Python functions into their own files without leaving the original module broken.

It creates a modules/ package next to the source file, moves the function there, and rewrites the source module to import it back in.

What it does

• Splits one top-level function with splitfunc.
• Splits every top-level function in a file, or every top-level function in each Python file in a directory, with splitall.
• Checks whether a split is safe, and shows the planned changes without writing files, with check.
• Copies the imports and top-level definitions the extracted function needs.
• Maintains modules/__init__.py so rewritten files can use a single merged import line.

Quick example

Starting point:

import math


def area(radius: float) -> float:
    return math.pi * radius * radius


def greet(name: str) -> str:
    return f"Hello, {name}!"

Run:

uv run manasplice splitfunc main.area

Result:

import math
from modules import area


def greet(name: str) -> str:
    return f"Hello, {name}!"

"""Auto-generated by ManaSplice from main.py."""

import math


def area(radius: float) -> float:
    return math.pi * radius * radius

Installation

For using in a project:

uv add manasplice

or

pip install manasplice

For local development in this repo:

uv sync

To run the CLI without installing it globally:

uv run manasplice --help

Commands

manasplice splitfunc <module>.<function>
manasplice splitall <path/to/file.py>
manasplice splitall --dir <directory>
manasplice check <module>.<function>
manasplice check <path/to/file.py>
manasplice check --dir <directory>
manasplice undo [count]
manasplice splitfunc <module>.<function> --preview
manasplice splitall <path/to/file.py> --preview
manasplice splitfunc <module>.<function> --validate
manasplice splitall <path/to/file.py> --public-only --exclude main,_*
manasplice splitall <path/to/file.py> --auto-group
manasplice splitfunc <module>.<function> --output-package generated
manasplice splitfunc <module>.<function> --force

Examples:

uv run manasplice splitfunc main.area
uv run manasplice splitfunc package.utils.normalize_name
uv run manasplice splitall main.py
uv run manasplice splitall --dir app
uv run manasplice check main.area
uv run manasplice check main.py --public-only --exclude main,_*
uv run manasplice splitall main.py --preview
uv run manasplice splitall main.py --public-only --exclude main,_*
uv run manasplice splitall main.py --auto-group
uv run manasplice splitfunc main.area --validate
uv run manasplice splitfunc main.area --output-package generated
uv run manasplice undo

Notes

• ManaSplice only moves top-level functions.
• splitall is literal: it will split every top-level function it finds, including helper functions and main() if present.
• Use check for a no-write safety report without diffs.
• Use --preview to inspect planned edits with a safety report and unified diffs before ManaSplice writes anything.
• Use --validate to make ManaSplice parse the generated Python source before it writes changes.
• Use --include, --exclude, and --public-only to make splitall selective instead of splitting every top-level function.
• Use --auto-group to keep top-level functions that reference each other in the same generated module.
• Use --output-package if you want generated modules somewhere other than modules/.
• ManaSplice refuses to overwrite an existing generated module unless you pass --force.
• ManaSplice refuses splits that depend on mutable top-level globals, because copying those globals into a new module changes runtime state.
• ManaSplice now refuses to split functions that participate in a local top-level dependency cycle, such as simple mutual recursion.
• Every non-preview split records rollback history in .manasplice_history.json, and undo replays the last recorded operation.
• The generated modules/ package is part of the rewritten code, not just scratch output.

Development

Run tests with:

uv run python -m pytest tests --basetemp .pytest_tmp
uv run ruff check src tests
uv run mypy

CONTRIBUTION

Feel free to give feedback and/or suggest changes. This is just meant to be a helpful tool for larger projects made for fun.