pyreorder

AST-based Python module reorganizer.

preorder reorders the top-level statements of a Python module into a canonical section layout (imports → globals → constants → classes → functions → main) and reorders the methods inside each class by visibility and type. It is built on libcst, so comments and formatting are preserved.

It is a module reorganizer: it focuses on grouping and ordering imports/globals/constants/classes/methods/etc. It does not integrate with other sorting tools (isort, undersort, etc.) or provide ruff subcommands.

Install

uv tool install pyreorder
preorder --version

Quick start

preorder run src/                 # sort files in place
preorder check src/               # exit 1 if anything would change (CI / pre-commit)
preorder diff src/                # preview changes
preorder config generate          # write/print a pyreorder.toml template (--with-comments, --with-config)

Before → after

Given this module:

import sys

def main():
    greet()

def greet():
    print("hi")

class Service:
    def _close(self):
        ...
    def start(self):
        ...

MAX_CONN = 10

if __name__ == "__main__":
    main()

preorder run (with functions = "stepdown") produces:

import sys

MAX_CONN = 10

class Service:
    def start(self):
        ...
    def _close(self):     # public methods first, then protected

def main():               # caller before callee (step-down rule)
    greet()

def greet():
    print("hi")

if __name__ == "__main__":
    main()

Configuration

Discovered from (first wins, walking up from the target file): --config, pyreorder.toml, .config/pyreorder.toml, [tool.preorder] in pyproject.toml.

[tool.preorder.module]
sections = [
    "imports", "typing_imports", "module_constants", "enums",
    "dataclasses", "classes", "functions", "dunder_exports", "main_block",
]

[tool.preorder.strategy]            # per-section; omit => "keep"
enums = "alpha"
functions = "stepdown"           # "alpha" | "stepdown" | "abstraction" | "keep"

[tool.preorder.class_methods]       # undersort-style ordering within each class
enabled = true
order = ["public", "protected", "private"]
method_type_order = ["instance", "class", "static"]

Strategies

Caution: alpha on module_constants / classes / dataclasses can break runtime order (interdependent constants, inheritance). Always preview with preorder diff first.

Safety model

preorder is conservative by design:

• Barriers — statements that don't map to a configured section (runtime setup like app = typer.Typer()) are never moved. Recognised statements only reorder within their contiguous barrier-free run, so preorder never moves code across a statement it might depend on.
• Pinned — the module docstring and from __future__ import ... always stay first.
• Opt-out — a # preorder: off (or # nosort) comment in a file's header skips the file; class C: # preorder: off skips that class.
• Idempotent — running preorder twice never changes a file a second time.

Programmatic API

from pyreorder import sort_source, Config

cfg = Config(strategies={"functions": "stepdown"})
sorted_text = sort_source(source_text, cfg)

Pre-commit

repos:
  - repo: https://github.com/jr2804/pyreorder
    rev: v0.1.0
    hooks:
      - id: preorder

Agent skill

An installable agent skill lives in skills/pyreorder. Install it for your AI assistant:

bun x skills add https://github.com/jr2804/pyreorder.git -s pyreorder -a universal -y

Development

uv sync --dev           # install dev dependencies
uv run pytest           # tests
uvx ruff check .        # lint
uvx ruff format .       # format

Acknowledgements

The in-class method sorter is an adapted reimplementation of undersort (MIT). Dependency-aware function ordering was inspired by ssort, sdsort and ABSort. See Credits.

License

MIT — see LICENSE.