Metadata-Version: 2.4
Name: funkshway
Version: 2026.6.1
Summary: Improve reading flow by arranging functions and other code blocks.
Project-URL: Source, https://gitlab.com/lfdo/incubator/funkshway
Author-email: David Seaward <72779-lofidevops@users.noreply.gitlab.com>
License-Expression: Apache-2.0
License-File: COPYING
Requires-Python: >=3.12
Requires-Dist: libcst>=1.3.1
Description-Content-Type: text/markdown

# 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

```sh
# 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 .
```

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`.

## Development environment

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

See `just --list` for additional SDLC commands.

### Publish

To publish a release:

```sh
just publish <yyyy.m.b>  # e.g. just release 2026.6.1
```

This requires an authenticated `glab` CLI.

New releases are delivered from GitLab to PyPI via
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/#gitlab-cicd).

## Sharing and contributions

```txt
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.
