FuncLoom

The Python functionizer. Turn Python snippets, scripts and Jupyter notebooks into reviewable functions and modular packages; every transformation is verified or refused with a reason and source location.

Part of a family of standalone Python tools: FuncLoom (functionizer), RefacTrail (refactorizer) and RepoContour (architect, planned). Each installs and works on its own.

0.10.3a0 is an unpublished experimental alpha. It has no runtime dependencies and does not need an LLM, account or network connection. Python 3.12 or newer is required. CI tests CPython 3.12-3.14 on Windows, Linux and macOS, and verifies the built packages on all three.

Quick start

pip install funcloom

That is all: FuncLoom has no dependencies. Python 3.12 or newer is required. Until the first PyPI release, install from GitHub instead: pip install git+https://github.com/SAMtheROCKET/funcloom.git.

Then, in any project:

funcloom                                     # the most useful commands
funcloom check script.py                     # long functions, structure
funcloom snippet code.py                     # draft a reusable function
funcloom modularize notebook.ipynb --output my_package
funcloom refine script.py --output script_refined.py

Your original files are never changed: results go to a new file or an empty folder, and anything that cannot be proven safe is refused with a reason and line number. If your system blocks the funcloom command, use python -m funcloom instead.

In VS Code, install the FuncLoom extension and run FuncLoom: ... from the Command Palette. It uses the Python interpreter selected in VS Code and offers to install FuncLoom there with one click.

On every commit, add the hook to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/SAMtheROCKET/funcloom
    rev: v0.10.3a0
    hooks:
      - id: funcloom-check

From source (development)

python -m venv .venv
.venv/bin/python -m pip install -e .      # Windows: .venv\Scripts\python.exe
.venv/bin/python -m funcloom doctor

Capabilities

The tools parse and compile source without importing or executing target projects. Generated files require review and the target project's tests. Structural checks and regression results do not prove that arbitrary programs retain their behavior. Unknown types and meanings remain explicit; domain context is supplied by the user, not guessed from names.

Try the workflows

Use your environment's Python in place of python below.

python -m funcloom snippet examples/snippet_tax.py --no-context
python -m funcloom snippet examples/snippet_tax.py --context profiles/snippet_tax.toml
python -m funcloom snippet examples/snippet_generic.py --interactive
python -m funcloom snippet examples/snippet_generic.py --naming mathematical
python -m funcloom snippet examples/snippet_tax.ipynb --cell 2 --no-context
python -m funcloom modularize examples/modular_sales_report.py --output demo_sales
python demo_sales/main.py
python -m funcloom refine examples/long_functions.py --output demo_refined.py --document
python demo_refined.py
python -m funcloom check examples/clean_module.py --fail-on warning

snippet --interactive offers no context or a small project description, then optional naming/type/meaning information. It does not translate pseudocode or natural-language instructions into executable Python. Noninteractive commands work without domain context.

For whole repositories:

python -m funcloom modularize path/to/project --output path/to/project_modular
python -m funcloom refine path/to/project --output path/to/project_refined

Outputs must be new; modularization also accepts an empty destination folder. Folder outputs must be outside the input tree. Input files are preserved. Run a generated package from its output folder. modularize without --output only plans; --show-files includes the generated text. --format json exposes the corresponding report contract.

Generated package and limits

A typical package has config.py, functions.py/models.py, steps.py, pipeline.py and main.py. Its initial imports are retained once, in source order, in _imports.py; later imports stay where they occurred. Folder mode retains library paths and data and adds entry-script shims.

• plan and snippet produce review drafts with no apply operation.
• modularize and refine write new copies. Known unsupported cases are refused or left unchanged with a reason; not every behavior difference can be detected statically.
• Wildcard imports are refused for modularization; use explicit imports. Dynamic namespaces, serialization, module identity, reflection and file paths need particular review.
• Notebook cells run in document order without kernel state. Magics and shell escapes may be omitted, with notes; outputs do not establish types or hidden dependencies.
• Unsupported functions/blocks stay whole, even over the size target. Type hints are narrow static proposals and documentation is a skeleton.
• Line length defaults to 79, configurable from 40 to 200. Existing tool directives are retained or refused. Wrapping that would create a new directive is refused too.
• No performance comparison with Ruff or Black has been established. Natural-language code generation and architecture diagrams remain future work. A local VSIX now supplies explicit check, snippet, modularize and refine commands; see editor setup.

See snippet context, generic variable names, extraction planning, modularization, refinement, rule coverage, and local/editor setup.

Development and release checks

.\.venv\Scripts\python.exe scripts/verify.py
.\.venv\Scripts\python.exe -m pip install -e ".[release]"
.\.venv\Scripts\python.exe scripts/release_check.py --output dist/0.10.2a0-final

The release check requires a new output directory. It builds a wheel and source archive, checks metadata and contents, installs into fresh environments, runs full verification against installed packages, and checks uninstallation. It writes logs, checksums and verification.json, with no upload step. See release preparation.

Python APIs and report schemas may change during the alpha. FuncLoom, RefacTrail and RepoContour remain separately releasable projects.

License

MIT, copyright 2026 Sambit Supriya Dash.