funkshway 🕺

Improve reading flow by arranging functions and other code blocks.

The formatter applies the following prioritized ordering:

• Idiomatic structure (dunders and other conventions)
• Topological order (callers before the helpers they use)
• Lexical order (for a stable, idempotent layout)

Usage

# Format specific files in-place
funkshway path/to/file.py [other/files.py ...]

# Recursive mode from current folder
funkshway .

# Log errors but exit with zero (relaxed mode for CI)
funkshway --relaxed .

# Check if files need formatting (exit 1 if so, no changes written)
funkshway --check .

# Show a unified diff of what would change (no changes written)
funkshway --diff .

# Write a JSON report of issues encountered (works in all modes)
funkshway --check --report issues.json .

Unresolvable code blocks will trigger an error, and that file will be skipped.

Vertical space and other formatting

• Vertical spacing: funkshway enforces minimal PEP 8 vertical spacing (e.g., two blank lines before top-level functions and classes) to ensure reordered code is immediately compatible with standard linters.
• Out of scope: All other formatting (indentation, line length, internal whitespace, etc.) is ignored. It is recommended to run ruff format or black after funkshway.

Triaging issues in the wild

When run over unfamiliar code, --report (or -r) writes a JSON document listing every issue that prevented a clean format — refusals, syntax errors, internal errors and warnings — with category, path, kind, line and snippet, plus a summary histogram ranked by frequency. Pair it with --check for a read-only survey, or with --relaxed to format what you can and report the rest. The histogram shows which unrecognized constructs occur most often, to evaluate them for inclusion in the ordering rules.

Development environment

Initialize with just bootstrap (includes linters). Test with just test.

See just --list for additional SDLC commands.

Publishing

To publish a release:

glab auth login
just publish

The new release is automatically delivered to PyPI via Trusted Publishing.

You may update the release notes in GitLab after the fact.

Sharing and contributions

funkshway 🕺
https://lofidevops.neocities.org
Copyright 2026 David Seaward and contributors
SPDX-License-Identifier: Apache-2.0

Shared under Apache-2.0. We adhere to the Contributor Covenant 3.0, and certify origin per DCO 1.1 with a signed-off-by line. Contributions under the same terms are welcome.

Submit security and conduct issues as private tickets. Sign commits with git commit --signoff. For a software bill of materials run reuse spdx. For more details see CONDUCT, COPYING and CONTRIBUTING.

Colophon

Feng shui is the practice of arranging objects to improve flow.

Built (almost) exclusively with AGENTS.md, specification.toml and PLAN.md for agent guidance.