Towel

Towel finds repeated Python code and extracts it into shared helper functions. Preview the changes, review the generated code, give the helpers meaningful names, and run your project's tests before adopting the result.

Release status: 1.949 (beta). At the November 8, 2026 preparation checkpoint, this candidate is unpublished and its release validation is in progress. At that checkpoint: Latest published release: 1.948. Check the GitHub releases for completed validation and publication records.

Install

The PyPI package is code-towel; the command is towel. The PyPI name towel belongs to an unrelated project, so pip install towel and uvx towel will not install this tool.

pip install code-towel
towel --version
towel --help

The runtime uses only the standard library. Optional tools format inserted code and annotate and type-check generated helpers:

pip install "code-towel[format,types]"

Towel uses these tools when installed; --no-format and --no-types turn either behavior off. Update with pip install --upgrade code-towel, or run without installing with uvx --from code-towel towel --help.

Try it on your project

# See the proposed changes without modifying your project.
towel preview path/to/project

# Keep the original and write into a fresh sibling directory.
towel dry path/to/project path/to/cleaned --no-interactive

# Review the result before adopting it. diff exits 1 when it finds changes.
diff -ru path/to/project path/to/cleaned

The output path must not already exist or overlap the input. Helpers are shared within a module by default; --cross-module also shares them between modules. A complete preview runs the full transformation pipeline. --quick gives a partial structural listing, which does not predict the final result.

Follow the runnable quick start for a complete example through extraction, naming, tests and adoption. The naming guide includes a manual rename mapping; no LLM account is required.

What to expect

Towel checks source correspondence, bindings, control flow and evaluation order, then declines transformations that fail those checks. An extraction must also repay the complexity of its helper and callers. Some repeated code is better left as it is.

Helpers initially have names such as __extracted_func_0. Preserving evaluation and cleanup order can require lookup functions or argument-lifetime bookkeeping. Review the whole change, including callers. The generated-code guide explains those cases; the command-line guide covers exclusions, bounded runs, output formats and recovery.

Requirements

Python 3.11 to 3.13 on a POSIX system (macOS or Linux). Applying changes needs POSIX filesystem semantics. Parallel analysis uses the fork start method; under other start methods analysis runs on a single core. Windows is not a supported or validated release platform.

One core is enough; TOWEL_WORKERS=1 limits analysis to one worker. Memory, disk use and run time depend on the project and enabled tools. See requirements and resources and performance measurements for measured workloads and their conditions.

Checks and limitations

Towel's soundness requirement is to preserve the behavior of programs that do not use reflection or self-instrumentation, including through code they call. An accepted transformation that changes such a program's behavior is a bug; Towel must fix the transformation or refuse it.

Reflection and source, AST, bytecode, frame or namespace inspection are outside its preservation guarantee, as is instrumentation that uses them to transform functions or classes. Towel does not scan for these behaviors or refuse code to protect them; decorators, ordinary calls and hooks have the same boundary. Protect sensitive definitions with # towel: no-extract immediately after the signature's final colon. The function opt-out guide explains its placement and limits. Mark the frame whose identity matters, including when its callee inspects it. The marker preserves that definition's source, not module namespaces, absolute line numbers or unmarked call chains. Review the known limitations and run your tests before adopting changes.

In annotated projects, Towel uses the configured type checkers when available and preserves caller-side narrowing. Existing checker errors are compared against a baseline; a checker that cannot run refuses typed extraction. The typing guide explains this policy and the unverified --no-types option.

Documentation and development

The documentation index groups tutorials, task guides, technical reference, design decisions and release evidence. Contributors can start with development setup and checks; release maintainers should follow the release procedure. Report security issues through the security policy.

License

Towel is licensed under the Apache License 2.0; its source files carry Eric Allen copyright headers.

Releases and validation

1.948 repairs four silent dry miscompilations found in 1.947. Its published release retains the completed validation record and artifacts under their original source identity. Earlier releases and their evidence remain in the release history.