true-formatter 0.1.0__py3-none-any.whl

true_formatter/__init__.py

@@ -0,0 +1,28 @@
+from .core import (
+    Mode,
+    TargetVersion,
+    format_str,
+    format_file_contents,
+    check_format,
+)
+from .cli import main
+from .exceptions import TrueError, TrueFormattingError, TrueConfigError
+from .rules import Rule, RuleSet, DEFAULT_RULES
+
+__all__ = [
+    "format_str",
+    "format_file_contents",
+    "check_format",
+    "main",
+    "Mode",
+    "TargetVersion",
+    "Rule",
+    "RuleSet",
+    "DEFAULT_RULES",
+    "TrueError",
+    "TrueFormattingError",
+    "TrueConfigError",
+]
+
+__version__ = "0.1.0"
+__author__ = "True Contributors"

true_formatter/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

true_formatter/cli.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .core import Mode, format_file_contents, check_format
+from .exceptions import TrueFormattingError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="true",
+        description="True — the uncompromising Python formatter.",
+    )
+    p.add_argument(
+        "src",
+        metavar="SRC",
+        nargs="*",
+        help="Files or directories to format (use '-' for stdin).",
+    )
+    p.add_argument(
+        "--check",
+        action="store_true",
+        help="Don't write files; exit non-zero if any would change.",
+    )
+    p.add_argument(
+        "--diff",
+        action="store_true",
+        help="Show a diff of changes instead of rewriting.",
+    )
+    p.add_argument(
+        "-l",
+        "--line-length",
+        type=int,
+        default=88,
+        metavar="INT",
+        help="Maximum line length (default: 88).",
+    )
+    p.add_argument(
+        "-S",
+        "--skip-string-normalization",
+        action="store_true",
+        help="Don't normalise string quotes.",
+    )
+    p.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress all non-error output.",
+    )
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    mode = Mode(
+        line_length=args.line_length,
+        skip_string_normalization=args.skip_string_normalization,
+    )
+
+    if not args.src:
+        parser.print_help()
+        return 0
+
+    changed = 0
+    for src_path in _iter_sources(args.src):
+        changed += _process(src_path, mode, args)
+
+    if args.check:
+        return 1 if changed else 0
+    return 0
+
+
+def _iter_sources(srcs: list[str]):
+    for s in srcs:
+        if s == "-":
+            yield "-"
+            continue
+        p = Path(s)
+        if p.is_dir():
+            yield from p.rglob("*.py")
+        else:
+            yield p
+
+
+def _process(path, mode: Mode, args) -> int:
+    if path == "-":
+        src = sys.stdin.read()
+        filename = "<stdin>"
+    else:
+        src = Path(path).read_text(encoding="utf-8")
+        filename = str(path)
+
+    try:
+        formatted = format_file_contents(src, mode=mode)
+    except TrueFormattingError as exc:
+        print(f"error: {filename}: {exc}", file=sys.stderr)
+        return 0
+
+    if formatted == src:
+        if not args.quiet:
+            print(f"unchanged: {filename}")
+        return 0
+
+    if args.check:
+        if not args.quiet:
+            print(f"would reformat: {filename}")
+        return 1
+
+    if args.diff:
+        _show_diff(src, formatted, filename)
+        return 1
+
+    if path == "-":
+        sys.stdout.write(formatted)
+    else:
+        Path(path).write_text(formatted, encoding="utf-8")
+        if not args.quiet:
+            print(f"reformatted: {filename}")
+    return 1
+
+
+def _show_diff(original: str, formatted: str, filename: str) -> None:
+    import difflib
+
+    diff = difflib.unified_diff(
+        original.splitlines(keepends=True),
+        formatted.splitlines(keepends=True),
+        fromfile=f"original/{filename}",
+        tofile=f"formatted/{filename}",
+    )
+    sys.stdout.writelines(diff)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

true_formatter/core.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import tokenize
+import io
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Iterator
+
+from .rules import RuleSet, DEFAULT_RULES
+from .exceptions import TrueFormattingError
+
+
+class TargetVersion(Enum):
+    PY38 = (3, 8)
+    PY39 = (3, 9)
+    PY310 = (3, 10)
+    PY311 = (3, 11)
+    PY312 = (3, 12)
+
+
+@dataclass
+class Mode:
+    target_versions: set[TargetVersion] = field(default_factory=set)
+    line_length: int = 88
+    string_normalization: bool = True
+    magic_trailing_comma: bool = True
+    skip_string_normalization: bool = False
+    rules: RuleSet = field(default_factory=lambda: DEFAULT_RULES)
+
+    @property
+    def quote_char(self) -> str:
+        if self.skip_string_normalization or not self.string_normalization:
+            return "'"
+        return '"'
+
+
+def format_str(src_contents: str, *, mode: Mode) -> str:
+    if not isinstance(src_contents, str):
+        raise TypeError(f"src_contents must be str, got {type(src_contents).__name__!r}")
+    try:
+        tokens = list(_tokenize(src_contents))
+    except tokenize.TokenError as exc:
+        raise TrueFormattingError(f"Cannot tokenize source: {exc}") from exc
+
+    transformed = _apply_rules(tokens, mode)
+    result = _emit(transformed, src_contents, mode)
+    return result
+
+
+def format_file_contents(src_contents: str, *, mode: Mode) -> str:
+    result = format_str(src_contents, mode=mode)
+    if not result.endswith("\n"):
+        result += "\n"
+    return result
+
+
+def check_format(src_contents: str, *, mode: Mode) -> bool:
+    try:
+        formatted = format_str(src_contents, mode=mode)
+    except TrueFormattingError:
+        return False
+    return formatted == src_contents
+
+
+def _tokenize(src: str) -> Iterator[tokenize.TokenInfo]:
+    yield from tokenize.generate_tokens(io.StringIO(src).readline)
+
+
+def _apply_rules(tokens: list[tokenize.TokenInfo], mode: Mode) -> list[tokenize.TokenInfo]:
+    result = tokens
+    for rule in mode.rules:
+        result = rule.apply(result, mode)
+    return result
+
+
+def _emit(tokens: list[tokenize.TokenInfo], original: str, mode: Mode) -> str:
+    try:
+        src = tokenize.untokenize(tokens)
+    except Exception:
+        src = original
+    return _text_level_format(src, mode)
+
+
+def _text_level_format(src: str, mode: Mode) -> str:
+    from .transforms import (
+        fix_indentation,
+        fix_multiple_imports,
+        split_semicolons,
+        fix_pep8_whitespace,
+        fix_operator_priority_spacing,
+        normalise_strings,
+        fix_trailing_whitespace,
+        fix_blank_lines,
+        ensure_final_newline,
+    )
+
+    src = fix_indentation(src)
+    src = fix_multiple_imports(src)
+    src = split_semicolons(src)
+    src = fix_pep8_whitespace(src)
+    src = fix_operator_priority_spacing(src)
+    if not mode.skip_string_normalization and mode.string_normalization:
+        src = normalise_strings(src, mode.quote_char)
+    src = fix_trailing_whitespace(src)
+    src = fix_blank_lines(src)
+    src = ensure_final_newline(src)
+    return src

true_formatter/exceptions.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+
+class TrueError(Exception):
+    pass
+
+
+class TrueFormattingError(TrueError):
+    pass
+
+
+class TrueConfigError(TrueError):
+    pass

true_formatter/rules.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import tokenize
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core import Mode
+
+
+class Rule(ABC):
+    name: str = "unnamed"
+
+    @abstractmethod
+    def apply(
+        self,
+        tokens: list[tokenize.TokenInfo],
+        mode: "Mode",
+    ) -> list[tokenize.TokenInfo]: ...
+
+
+class NormaliseCommaSpacing(Rule):
+    name = "comma-spacing"
+
+    def apply(self, tokens, mode):
+        out: list[tokenize.TokenInfo] = []
+        for i, tok in enumerate(tokens):
+            out.append(tok)
+        return out
+
+
+class NormaliseColonSpacing(Rule):
+    name = "colon-spacing"
+
+    def apply(self, tokens, mode):
+        return tokens
+
+
+class RemoveExtraParens(Rule):
+    name = "extra-parens"
+
+    def apply(self, tokens, mode):
+        return tokens
+
+
+@dataclass
+class RuleSet:
+    rules: list[Rule]
+
+    def __iter__(self):
+        return iter(self.rules)
+
+    def __len__(self):
+        return len(self.rules)
+
+    def add(self, rule: Rule) -> "RuleSet":
+        return RuleSet(rules=[*self.rules, rule])
+
+    def remove(self, name: str) -> "RuleSet":
+        return RuleSet(rules=[r for r in self.rules if r.name != name])
+
+
+DEFAULT_RULES = RuleSet(
+    rules=[
+        NormaliseCommaSpacing(),
+        NormaliseColonSpacing(),
+        RemoveExtraParens(),
+    ]
+)

true_formatter/transforms.py

@@ -0,0 +1,586 @@
+from __future__ import annotations
+
+import re
+import tokenize
+import io
+from collections import defaultdict
+
+# ─── string normalisation ─────────────────────────────────────────────────────
+
+def normalise_strings(src: str, quote_char: str = '"') -> str:
+    result: list[str] = []
+    tokens = _safe_tokenize(src)
+    prev_end = 0
+    for tok in tokens:
+        if tok.type != tokenize.STRING:
+            continue
+        start_offset = _offset(src, tok.start)
+        end_offset = _offset(src, tok.end)
+        result.append(src[prev_end:start_offset])
+        result.append(_rewrite_string(tok.string, quote_char))
+        prev_end = end_offset
+    result.append(src[prev_end:])
+    return "".join(result)
+
+
+def _rewrite_string(raw: str, quote_char: str) -> str:
+    for triple in ('"""', "'''"):
+        if raw.lstrip("rRbBuUfF").startswith(triple):
+            return raw
+    prefix = ""
+    rest = raw
+    while rest and rest[0].lower() in "rbuf":
+        prefix += rest[0]
+        rest = rest[1:]
+    if not rest or rest[0] not in ('"', "'"):
+        return raw
+    current_quote = rest[0]
+    if current_quote == quote_char:
+        return raw
+    inner = rest[1:-1]
+    if quote_char in inner:
+        return raw
+    inner = inner.replace(f"\\{current_quote}", current_quote)
+    return f"{prefix}{quote_char}{inner}{quote_char}"
+
+
+# ─── PEP 8 token-based whitespace fixer ──────────────────────────────────────
+
+_OPENING = {"(", "[", "{"}
+_CLOSING = {")", "]", "}"}
+
+_BINARY_OPS = {
+    "+", "-", "*", "/", "//", "%", "**",
+    "==", "!=", "<", ">", "<=", ">=",
+    "&", "|", "^", "<<", ">>",
+    "+=", "-=", "*=", "/=", "//=", "%=", "**=",
+    "&=", "|=", "^=", "<<=", ">>=",
+    "->", "@", "@=",
+}
+
+_UNARY_PREV_OPS = _OPENING | {
+    ",", ";", "=", ":", "+=", "-=", "*=", "/=",
+    "//=", "%=", "**=", "&=", "|=", "^=", "<<=", ">>=",
+    "==", "!=", "<", ">", "<=", ">=", "&", "|", "^",
+    "<<", ">>", "//", "%", "**", "+", "-", "*", "/",
+    "return", "yield", "not", "and", "or", "in", "is",
+    "lambda", "else", "if",
+}
+
+_KEYWORD_BEFORE_PAREN = {
+    "if", "else", "elif", "while", "for", "with",
+    "assert", "return", "yield", "del", "and", "or",
+    "not", "in", "is", "lambda", "class", "def",
+    "import", "from", "raise", "except", "as",
+}
+
+
+def fix_pep8_whitespace(src: str) -> str:
+    tokens = _safe_tokenize(src)
+    if not tokens:
+        return src
+
+    meaningful = [
+        t for t in tokens
+        if t.type not in (
+            tokenize.ENCODING, tokenize.NL, tokenize.NEWLINE,
+            tokenize.INDENT, tokenize.DEDENT, tokenize.ENDMARKER,
+        )
+    ]
+
+    n = len(meaningful)
+
+    def prev_m(i):
+        return meaningful[i - 1] if i > 0 else None
+
+    def next_m(i):
+        return meaningful[i + 1] if i + 1 < n else None
+
+    # space_before[i] = desired whitespace string before meaningful[i]
+    # None means "keep whatever is in the original source"
+    space_before: list[str | None] = [None] * n
+
+    # Track paren depth stack: each entry is the token string that opened it
+    # to distinguish  def foo(  vs  foo(
+    paren_stack: list[str] = []   # 'def'/'class' or 'call' or 'other'
+
+    def in_params() -> bool:
+        return bool(paren_stack) and paren_stack[-1] in ("def", "class")
+
+    def in_brackets() -> bool:
+        return bool(paren_stack)
+
+    for i, tok in enumerate(meaningful):
+        p = prev_m(i)
+        nx = next_m(i)
+        s = tok.string
+        tt = tok.type
+
+        # ── track bracket depth ──────────────────────────────────────────────
+        if s in _OPENING:
+            # look two tokens back: def foo( — p is 'foo', pp is 'def'
+            pp = meaningful[i - 2] if i >= 2 else None
+            if p and p.type == tokenize.NAME and p.string in ("def", "class", "lambda"):
+                paren_stack.append("def")
+            elif pp and pp.type == tokenize.NAME and pp.string in ("def", "class", "lambda"):
+                paren_stack.append("def")
+            elif p and p.type == tokenize.NAME and p.string not in _KEYWORD_BEFORE_PAREN:
+                paren_stack.append("call")
+            elif p and p.type == tokenize.OP and p.string in (")", "]"):
+                paren_stack.append("call")
+            else:
+                paren_stack.append("other")
+
+        if s in _CLOSING and paren_stack:
+            paren_stack.pop()
+
+        # ── E201: no space after opening bracket ─────────────────────────────
+        if s in _OPENING:
+            if nx and nx.string not in _CLOSING:
+                space_before[i + 1] = ""
+
+        # ── E202: no space before closing bracket ────────────────────────────
+        if s in _CLOSING:
+            if p and p.string not in _OPENING:
+                space_before[i] = ""
+
+        # ── E203: no space before , ; ────────────────────────────────────────
+        if s in (",", ";"):
+            space_before[i] = ""
+
+        # ── E231: space after , ; ────────────────────────────────────────────
+        if s in (",", ";"):
+            if nx and nx.string not in _CLOSING and nx.start[0] == tok.start[0]:
+                space_before[i + 1] = " "
+
+        # ── E203: no space before colon (dict, class, def, if, etc.) ──────────
+        if s == ":":
+            space_before[i] = ""
+            if in_brackets() and paren_stack[-1] == "other":
+                if nx and nx.string not in _CLOSING and nx.start[0] == tok.start[0]:
+                    space_before[i + 1] = " "
+
+        # ── E211: no space before ( or [ used as call/index ──────────────────
+        if s in ("(", "["):
+            if p and p.type == tokenize.NAME and p.string not in _KEYWORD_BEFORE_PAREN:
+                space_before[i] = ""
+            elif p and p.type == tokenize.OP and p.string in (")", "]"):
+                space_before[i] = ""
+
+        # ── E225: spaces around binary operators ─────────────────────────────
+        if tt == tokenize.OP and s in _BINARY_OPS:
+            is_unary = False
+            if s in ("+", "-", "~", "*", "**"):
+                if p is None:
+                    is_unary = True
+                elif p.type == tokenize.OP and (p.string in _UNARY_PREV_OPS or p.string in _OPENING):
+                    is_unary = True
+                elif p.type == tokenize.NAME and p.string in _UNARY_PREV_OPS:
+                    is_unary = True
+                elif p.type in (tokenize.NEWLINE, tokenize.NL, tokenize.INDENT):
+                    is_unary = True
+
+            if not is_unary:
+                space_before[i] = " "
+                if nx and nx.start[0] == tok.start[0]:
+                    space_before[i + 1] = " "
+
+        # ── E251/E252: = spacing in params depends on annotation ─────────────
+        if s == "=" and in_brackets() and in_params():
+            # Check if this param is annotated: look back for : between last , or ( and here
+            annotated = _param_is_annotated(meaningful, i)
+            if annotated:
+                # E252: annotated default → keep spaces  def f(x: int = 1)
+                space_before[i] = " "
+                if nx and nx.start[0] == tok.start[0]:
+                    space_before[i + 1] = " "
+            else:
+                # E251: unannotated default → no spaces  def f(x=1)
+                space_before[i] = ""
+                if nx and nx.start[0] == tok.start[0]:
+                    space_before[i + 1] = ""
+
+        # ── E251 for call keyword args:  foo(x =1) → foo(x=1) ────────────────
+        if s == "=" and in_brackets() and paren_stack[-1] == "call":
+            space_before[i] = ""
+            if nx and nx.start[0] == tok.start[0]:
+                space_before[i + 1] = ""
+
+        # ── plain assignment at statement level ───────────────────────────────
+        if s == "=" and not in_brackets():
+            space_before[i] = " "
+            if nx and nx.start[0] == tok.start[0]:
+                space_before[i + 1] = " "
+
+    return _rebuild(src, meaningful, space_before)
+
+
+def _rebuild(src: str, meaningful: list, space_before: list[str | None]) -> str:
+    # Map start position → desired space before token
+    space_map: dict[tuple[int, int], str] = {}
+    for i, tok in enumerate(meaningful):
+        if space_before[i] is not None:
+            space_map[tok.start] = space_before[i]
+
+    lines = src.splitlines(keepends=True)
+    by_line: dict[int, list] = defaultdict(list)
+    for tok in _safe_tokenize(src):
+        if tok.type not in (tokenize.ENCODING, tokenize.ENDMARKER):
+            by_line[tok.start[0]].append(tok)
+
+    out_lines: list[str] = []
+
+    for lineno, line in enumerate(lines, 1):
+        toks = [
+            t for t in by_line.get(lineno, [])
+            if t.type not in (
+                tokenize.INDENT, tokenize.DEDENT,
+                tokenize.NL, tokenize.NEWLINE, tokenize.ENCODING,
+            )
+            and t.start[0] == lineno
+        ]
+        if not toks:
+            out_lines.append(line)
+            continue
+
+        stripped = line.lstrip()
+        indent = line[: len(line) - len(stripped)]
+        eol = "\n" if line.endswith("\n") else ""
+
+        parts: list[str] = [indent]
+        for j, tok in enumerate(toks):
+            if j == 0:
+                parts.append(tok.string)
+                continue
+
+            prev_tok = toks[j - 1]
+            original_gap = line[prev_tok.end[1]:tok.start[1]]
+            desired = space_map.get(tok.start)
+            gap = desired if desired is not None else original_gap
+
+            # E261/E262: inline comment needs 2 spaces before, "# " after hash
+            if tok.type == tokenize.COMMENT:
+                gap = "  "
+                comment = tok.string
+                if len(comment) > 1 and comment[1] not in (" ", "!"):
+                    comment = "# " + comment[1:]
+                parts.append(gap)
+                parts.append(comment)
+                continue
+
+            parts.append(gap)
+            parts.append(tok.string)
+
+        out_lines.append("".join(parts) + eol)
+
+    return "".join(out_lines)
+
+
+# ─── operator spacing fallback (simple regex) ─────────────────────────────────
+
+def fix_operator_spacing(src: str) -> str:
+    lines = src.splitlines(keepends=True)
+    out: list[str] = []
+    for line in lines:
+        out.append(_fix_line(line))
+    return "".join(out)
+
+
+def _fix_line(line: str) -> str:
+    stripped = line.lstrip()
+    if not stripped or stripped.startswith("#"):
+        return line
+    indent = line[: len(line) - len(line.lstrip())]
+    code = stripped.rstrip("\n\r")
+    eol = line[len(indent) + len(code):]
+    code = re.sub(r"(?<![=!<>+\-*/%&|^])(\s*)=(\s*)(?![=])", lambda m: " = ", code)
+    code = re.sub(r"\s*([+\-*/%&|^]=)\s*", r" \1 ", code)
+    return indent + code + eol
+
+
+# ─── indentation ──────────────────────────────────────────────────────────────
+
+def fix_indentation(src: str) -> str:
+    try:
+        tokens = list(tokenize.generate_tokens(io.StringIO(src).readline))
+    except tokenize.TokenError:
+        return src
+
+    lines = src.splitlines(keepends=True)
+    token_by_line: dict[int, list] = defaultdict(list)
+    for tok in tokens:
+        token_by_line[tok.start[0]].append(tok)
+
+    current_depth = 0
+    out: list[str] = []
+    for i, line in enumerate(lines):
+        lineno = i + 1
+        stripped = line.lstrip()
+        eol = "\n" if line.endswith("\n") else ""
+        if not stripped:
+            out.append(eol)
+            continue
+        for tok in token_by_line.get(lineno, []):
+            if tok.type == tokenize.INDENT:
+                current_depth += 1
+            elif tok.type == tokenize.DEDENT:
+                current_depth = max(0, current_depth - 1)
+        out.append("    " * current_depth + stripped.rstrip("\n\r") + eol)
+    return "".join(out)
+
+
+# ─── blank lines ──────────────────────────────────────────────────────────────
+
+_TOP_LEVEL_DEF = re.compile(r"^(class |def |async def )")
+_METHOD_DEF = re.compile(r"^(def |async def )")
+
+
+def fix_blank_lines(src: str) -> str:
+    lines = src.splitlines()
+    out: list[str] = []
+    for i, line in enumerate(lines):
+        stripped = line.lstrip()
+        indent = len(line) - len(stripped)
+
+        # Two blank lines before top-level class/def
+        if _TOP_LEVEL_DEF.match(stripped) and indent == 0:
+            while out and out[-1].strip() == "":
+                out.pop()
+            if out:
+                out.append("")
+                out.append("")
+
+        # One blank line before methods inside a class (indented def)
+        elif _METHOD_DEF.match(stripped) and indent > 0:
+            # Only add if previous non-blank line is not an opening class body
+            prev_nonblank = next((l for l in reversed(out) if l.strip()), "")
+            if out and prev_nonblank.strip() not in ("", ) and not prev_nonblank.rstrip().endswith(":"):
+                while out and out[-1].strip() == "":
+                    out.pop()
+                if out:
+                    out.append("")
+
+        out.append(line)
+    return "\n".join(out)
+
+
+# ─── imports ──────────────────────────────────────────────────────────────────
+
+def fix_multiple_imports(src: str) -> str:
+    lines = src.splitlines(keepends=True)
+    out: list[str] = []
+    for line in lines:
+        stripped = line.lstrip()
+        indent = line[: len(line) - len(stripped)]
+        eol = "\n" if line.endswith("\n") else ""
+        m = re.match(r"^import\s+(.+)$", stripped.rstrip())
+        if m:
+            names = [n.strip() for n in m.group(1).split(",")]
+            if len(names) > 1:
+                for name in names:
+                    out.append(f"{indent}import {name}{eol}")
+                continue
+        out.append(line)
+    return "".join(out)
+
+
+# ─── trailing whitespace / newline ────────────────────────────────────────────
+
+def fix_trailing_whitespace(src: str) -> str:
+    return "\n".join(l.rstrip() for l in src.splitlines())
+
+
+def ensure_final_newline(src: str) -> str:
+    return src.rstrip("\n") + "\n"
+
+
+# ─── helpers ──────────────────────────────────────────────────────────────────
+
+def _safe_tokenize(src: str) -> list:
+    try:
+        return list(tokenize.generate_tokens(io.StringIO(src).readline))
+    except tokenize.TokenError:
+        return []
+
+
+def _offset(src: str, rowcol: tuple[int, int]) -> int:
+    row, col = rowcol
+    lines = src.splitlines(keepends=True)
+    return sum(len(lines[r]) for r in range(row - 1)) + col
+
+
+def _param_is_annotated(meaningful: list, eq_index: int) -> bool:
+    """Return True if the = at eq_index belongs to an annotated parameter.
+
+    Walk backwards from eq_index to find the most recent , or ( at the same
+    bracket depth. If we find a : (annotation) before hitting , or (, the
+    param is annotated.
+    """
+    depth = 0
+    for j in range(eq_index - 1, -1, -1):
+        s = meaningful[j].string
+        if s in (")", "]", "}"):
+            depth += 1
+        elif s in ("(", "[", "{"):
+            if depth == 0:
+                return False  # hit opening paren — no annotation found
+            depth -= 1
+        elif depth == 0:
+            if s == ",":
+                return False  # hit comma — no annotation between , and =
+            if s == ":":
+                return True   # found annotation colon
+    return False
+
+
+# Priority groups (lower index = lower priority = MORE spaces)
+# PEP8: "in expressions with operators of different priorities, add spaces
+# around the operator with the lowest priority"
+_OP_PRIORITY: dict[str, int] = {
+    # lowest priority → spaces preferred
+    "or": 0, "and": 1, "not": 2,
+    "in": 3, "not in": 3, "is": 3, "is not": 3,
+    "<": 4, ">": 4, "<=": 4, ">=": 4, "==": 4, "!=": 4,
+    "|": 5, "^": 6, "&": 7,
+    "<<": 8, ">>": 8,
+    "+": 9, "-": 9,       # lower priority arithmetic → spaces
+    "*": 10, "/": 10, "//": 10, "%": 10, "@": 10,
+    "**": 11,             # highest priority → no spaces preferred
+}
+
+
+def fix_operator_priority_spacing(src: str) -> str:
+    """
+    PEP8: around operators of different priority in the same expression,
+    add spaces around the lower-priority operator and no spaces around
+    the higher-priority one.
+
+    e.g.  x*2 - 1      is correct   (- is lower priority than *)
+          x = x*2 - 1  stays as-is
+          hypot2 = x*x + y*y  stays
+    """
+    # This is a conservative line-level pass — only rewrite lines where
+    # a clear mix of priorities is obvious without a full AST.
+    # We leave ambiguous cases untouched.
+    lines = src.splitlines(keepends=True)
+    return "".join(_fix_priority_line(l) for l in lines)
+
+
+def _fix_priority_line(line: str) -> str:
+    stripped = line.lstrip()
+    if not stripped or stripped.startswith("#"):
+        return line
+    # Only touch lines that have at least one * or ** next to a + or -
+    # Pattern: space-then-op-then-space on low-priority, no-space on high-priority
+    # We just ensure the standard "no space around **" rule
+    import re as _re
+    # Remove spaces around ** (highest priority, PEP8 example: 2**10)
+    # Only when operands are simple (names/numbers)
+    line = _re.sub(r"(\w)\s+\*\*\s+(\w)", r"\1**\2", line)
+    return line
+
+
+def split_semicolons(src: str) -> str:
+    """Split statements separated by semicolons onto separate lines (E702/E401).
+
+    x = 0; y = 0   →   x = 0
+                        y = 0
+
+    Also splits compound statements on one line:
+    if True: pass  →  if True:
+                          pass
+    """
+    lines = src.splitlines(keepends=True)
+    out: list[str] = []
+    for line in lines:
+        out.extend(_split_line(line))
+    return "".join(out)
+
+
+def _split_line(line: str) -> list[str]:  # noqa: C901
+    stripped = line.lstrip()
+    eol = "\n" if line.endswith("\n") else ""
+    indent = line[: len(line) - len(stripped)]
+
+    # Skip blank lines and comment-only lines
+    if not stripped or stripped.startswith("#"):
+        return [line]
+
+    # Tokenize to find semicolons outside strings/brackets
+    import tokenize as _tok
+    import io as _io
+
+    try:
+        tokens = list(_tok.generate_tokens(_io.StringIO(line).readline))
+    except _tok.TokenError:
+        return [line]
+
+    # Find semicolons at depth 0 (not inside brackets)
+    depth = 0
+    semi_cols: list[int] = []
+    for tok in tokens:
+        if tok.type == _tok.OP:
+            if tok.string in ("(", "[", "{"):
+                depth += 1
+            elif tok.string in (")", "]", "}"):
+                depth -= 1
+            elif tok.string == ";" and depth == 0:
+                # store relative column (subtract indent length)
+                semi_cols.append(tok.start[1] - len(indent))
+
+    # Handle compound statements FIRST (before semicolons)
+    # Handle compound statements: if/for/while/with/else/elif/try/except/finally: body
+    # e.g.  if x: do_thing()
+    _COMPOUND = re.compile(
+        r"^(if|elif|else|for|while|with|try|except|finally|class|def|async def|async for|async with)\b"
+    )
+    if _COMPOUND.match(stripped):
+        # Find the colon that ends the header (at depth 0)
+        # We want the FIRST colon at depth 0 that is followed by non-empty content
+        depth = 0
+        colon_col = None
+        for tok in tokens:
+            if tok.type == _tok.OP:
+                if tok.string in ("(", "[", "{"):
+                    depth += 1
+                elif tok.string in (")", "]", "}"):
+                    depth = max(0, depth - 1)
+                elif tok.string == ":" and depth == 0:
+                    # tok.start[1] is absolute column in line; adjust for indent
+                    abs_col = tok.start[1]
+                    rel_col = abs_col - len(indent)
+                    after = stripped[rel_col + 1:].strip()
+                    if after and not after.startswith("#"):
+                        colon_col = rel_col
+                        break  # take the first qualifying colon
+        if colon_col is not None:
+            header = stripped[: colon_col + 1].rstrip()
+            body = stripped[colon_col + 1 :].strip()
+            if body and not body.startswith("#"):
+                # Body may itself contain semicolons — recurse on body
+                body_lines = _split_line(indent + "    " + body + eol)
+                return [indent + header + eol] + body_lines
+
+    if semi_cols:
+        # Split on semicolons
+        result: list[str] = []
+        code = stripped.rstrip("\n\r")
+        parts = _split_at_cols(code, semi_cols)
+        for part in parts:
+            part = part.strip()
+            if part:
+                result.append(indent + part + eol)
+        return result
+
+    return [line]
+
+
+def _split_at_cols(code: str, semi_cols: list[int]) -> list[str]:
+    """Split a string at the given column positions (semicolons)."""
+    parts: list[str] = []
+    prev = 0
+    for col in semi_cols:
+        parts.append(code[prev:col])
+        prev = col + 1  # skip the semicolon
+    parts.append(code[prev:])
+    return parts

true_formatter-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: true-formatter
+Version: 0.1.0
+Summary: The uncompromising Python formatter.
+Author: True Contributors
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# True — The Uncompromising Python Formatter
+
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**True** is an opinionated Python source-code formatter inspired by [Black](https://github.com/psf/black).
+It enforces a consistent style so you never have to think about formatting again.
+
+---
+
+## Features
+
+- Normalises string quotes (`'hello'` → `"hello"`)
+- Removes trailing whitespace from every line
+- Enforces two blank lines before top-level `def` / `class`
+- Fixes spacing around `=` and binary operators
+- Guarantees a single trailing newline
+- Pluggable rule system — extend or disable any rule
+- Zero dependencies (pure stdlib)
+
+---
+
+## Installation
+
+```bash
+pip install true-formatter
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourname/true-formatter
+cd true-formatter
+pip install -e .[dev]
+```
+
+---
+
+## Quick start
+
+### As a CLI tool
+
+```bash
+# Format a file in-place
+true my_script.py
+
+# Check without modifying
+true --check my_script.py
+
+# Show a unified diff
+true --diff my_script.py
+
+# Format an entire directory
+true src/
+
+# Read from stdin
+echo "x=1" | true -
+```
+
+### As a library
+
+```python
+import true_formatter
+
+code = "x=1\ny=  'hello'\n"
+result = true_formatter.format_str(code, mode=true_formatter.Mode())
+print(result)
+# x = 1
+# y = "hello"
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [API Reference](docs/api.md) | Full public API — `format_str`, `Mode`, `RuleSet`, exceptions |
+| [CLI Reference](docs/cli.md) | All command-line flags and examples |
+| [Architecture](docs/architecture.md) | How the formatter pipeline works internally |
+| [Contributing](docs/contributing.md) | Writing rules, running tests, sending PRs |
+
+---
+
+## License
+
+MIT © True Contributors

true_formatter-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+true_formatter/__init__.py,sha256=6vftv8M66XOi21jkRWbm-_ECTCvfMygLnMHE_N1I1YQ,550
+true_formatter/__main__.py,sha256=nbdP6zFlOqcCirgxoIQ6HiWVhdh7URm5GOWr5_EwmBk,116
+true_formatter/cli.py,sha256=y004hnnSUJMBr8CVFiq8ksGdJmDYdMZZ9nF-6i0uxGo,3309
+true_formatter/core.py,sha256=8eEVX8twI1ReHrjfdsOgji5CtCJCrOXOOPzYAXnQfZI,3055
+true_formatter/exceptions.py,sha256=FXEmnDk57L6GNfs_uLi6RHRzybHbJpvNolrXErQMeMo,168
+true_formatter/rules.py,sha256=ONDitsRN3DhqJOXGiVPCnvtFlUpqbBpaMslyqQjQJ5E,1387
+true_formatter/transforms.py,sha256=fA1Za7WT4CtyisMFjcxkCsr0JGJa59_dWBE6HrS5f_c,22380
+true_formatter-0.1.0.dist-info/METADATA,sha256=YZLu1pKCNsCR41U70Am8X2P1CeW5RsT8unOihTN3ChQ,2430
+true_formatter-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+true_formatter-0.1.0.dist-info/entry_points.txt,sha256=VFgjqFP95rPkm_YTaXg4lLZElZTrHJj1U8qguZej0Z4,49
+true_formatter-0.1.0.dist-info/top_level.txt,sha256=RDlRJo9hJQPATlk_9I4IVpLVfCvjH8QG_pXJHui4PaU,15
+true_formatter-0.1.0.dist-info/RECORD,,

true_formatter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

true_formatter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+true = true_formatter.cli:main

true_formatter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+true_formatter