Metadata-Version: 2.4
Name: manasplice
Version: 0.1.0.3a0
Summary: Split top-level Python functions into dedicated modules and rewire imports automatically.
Author: VirtualShowdown
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: colorama>=0.4.6
Description-Content-Type: text/markdown

![image](media/icons/manasplit_tp.png)

> # 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:

```python
import math


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


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

Run:

```bash
uv run manasplice splitfunc main.area
```

Result:

```python
import math
from modules import area


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

```python
"""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:

```bash
uv add manasplice
```

or

```bash
pip install manasplice
```

For local development in this repo:

```bash
uv sync
```

To run the CLI without installing it globally:

```bash
uv run manasplice --help
```

## Commands

```bash
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:

```bash
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:

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

## _CONTRIBUTION_

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