keytidy 0.1.0__py3-none-any.whl

keytidy/__init__.py

@@ -0,0 +1,3 @@
+"""keytidy — tidy JSON key order, with smart package.json handling. Zero dependencies."""
+
+__version__ = "0.1.0"

keytidy/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

keytidy/cli.py

@@ -0,0 +1,164 @@
+"""keytidy command-line interface."""
+
+import json
+import os
+import sys
+
+from . import core
+
+VERSION = "0.1.0"
+
+# ---- tiny color helpers (no dep) ----
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+def red(s): return _c("31", s)
+def green(s): return _c("32", s)
+def yellow(s): return _c("33", s)
+def dim(s): return _c("2", s)
+def bold(s): return _c("1", s)
+
+
+HELP = f"""{bold('keytidy')} — tidy JSON key order (and package.json the way it's meant to look).
+
+{bold('Usage')}
+  keytidy [file...]      Sort & rewrite the files (defaults to ./package.json)
+  keytidy --check        Don't write; exit 1 if anything isn't sorted (CI)
+  keytidy --stdout       Print the sorted result instead of writing
+  keytidy *.json         Sort every JSON file (your shell expands the glob)
+
+{bold('Options')}
+  --indent <n|tab>   Override indentation (default: detected from the file, else 2)
+  --sort-scripts     Also sort package.json "scripts" (off — script order matters)
+  --all-keys         Sort package.json purely alphabetically (ignore the conventional order)
+  --version
+
+{bold('What it does')}
+  • generic JSON  — every object's keys sorted A->Z; arrays kept in order
+  • package.json  — conventional field order (name, version, …, dependencies),
+                    dependency blocks sorted A->Z, "scripts" left as you wrote it
+
+{bold('Exit')}  0 sorted/clean · 1 needs sorting (--check) · 2 bad JSON / IO error
+"""
+
+
+def die(msg):
+    sys.stderr.write(red(f"keytidy: {msg}\n"))
+    sys.exit(2)
+
+
+def parse_args(argv):
+    opts = {"files": [], "check": False, "stdout": False, "indent": None,
+            "sortScripts": False, "allKeys": False}
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--check":
+            opts["check"] = True
+        elif a == "--stdout":
+            opts["stdout"] = True
+        elif a == "--sort-scripts":
+            opts["sortScripts"] = True
+        elif a == "--all-keys":
+            opts["allKeys"] = True
+        elif a == "--indent":
+            i += 1
+            if i >= len(argv):
+                die('--indent needs a value (a number or "tab")')
+            v = argv[i]
+            if v == "tab":
+                opts["indent"] = "\t"
+            elif v.isdigit():
+                opts["indent"] = int(v)
+            else:
+                die('--indent must be a number or "tab"')
+        elif a.startswith("-"):
+            die(f"unknown flag: {a} (try --help)")
+        else:
+            opts["files"].append(a)
+        i += 1
+    return opts
+
+
+def resolve_files(files):
+    if files:
+        return files
+    if os.path.exists("package.json"):
+        return ["package.json"]
+    die("no files given and no ./package.json found — pass a JSON file")
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if "-h" in argv or "--help" in argv:
+        sys.stdout.write(HELP)
+        return 0
+    if "-v" in argv or "--version" in argv:
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    opts = parse_args(argv)
+    files = resolve_files(opts["files"])
+
+    errored = False
+    needs_sort = False
+
+    for file in files:
+        try:
+            with open(file, encoding="utf-8") as f:
+                text = f.read()
+        except FileNotFoundError:
+            sys.stderr.write(red(f"✗ {file} — no such file\n"))
+            errored = True
+            continue
+        except OSError as e:
+            sys.stderr.write(red(f"✗ {file} — {e}\n"))
+            errored = True
+            continue
+
+        try:
+            result = core.process(text, {
+                "packageJson": os.path.basename(file) == "package.json",
+                "indent": opts["indent"],
+                "sortScripts": opts["sortScripts"],
+                "allKeys": opts["allKeys"],
+            })
+        except (json.JSONDecodeError, ValueError) as e:
+            sys.stderr.write(red(f"✗ {file} — invalid JSON: {e}\n"))
+            errored = True
+            continue
+
+        if opts["stdout"]:
+            sys.stdout.write(result["output"])
+            continue
+        if opts["check"]:
+            if result["changed"]:
+                needs_sort = True
+                sys.stdout.write("{} {} {}\n".format(yellow("✗"), file, dim("— not sorted")))
+            else:
+                sys.stdout.write("{} {} {}\n".format(green("✓"), file, dim("— sorted")))
+            continue
+        # write mode
+        if result["changed"]:
+            try:
+                with open(file, "w", encoding="utf-8") as f:
+                    f.write(result["output"])
+            except OSError as e:
+                sys.stderr.write(red(f"✗ {file} — {e}\n"))
+                errored = True
+                continue
+            sys.stdout.write("{} {} {}\n".format(green("✓"), bold(file), dim("— sorted")))
+        else:
+            sys.stdout.write("{} {} {}\n".format(dim("•"), file, dim("— already sorted")))
+
+    if errored:
+        return 2
+    if opts["check"] and needs_sort:
+        if not opts["stdout"]:
+            sys.stdout.write("\n{} {} {}\n".format(dim("run"), bold("keytidy"), dim("to fix")))
+        return 1
+    return 0

keytidy/core.py

@@ -0,0 +1,96 @@
+"""keytidy core — pure JSON key-ordering logic. No fs, no process, no clock.
+
+Two jobs:
+
+  1. Generic JSON — recursively sort every object's keys alphabetically. Arrays
+     keep their order (arrays are data, not config); primitives are untouched.
+     The point is to kill the diff noise from tools that emit keys in arbitrary
+     order.
+  2. package.json — sorting it alphabetically would be *wrong* (``name`` should
+     come before ``dependencies``). So package.json gets the conventional field
+     order at the top level, its dependency objects sorted alphabetically, and
+     its ``scripts`` block left in the author's order.
+
+Mirrors the Node port behavior. The fs/CLI plumbing lives in cli.py.
+"""
+
+import json
+import re
+
+# Conventional top-level order for package.json (npm's own ordering plus what
+# the ecosystem settled on). Keys not in this list are appended alphabetically.
+PACKAGE_FIELD_ORDER = [
+    "$schema", "name", "displayName", "version", "private", "description",
+    "keywords", "license", "licenses", "homepage", "repository", "bugs", "funding",
+    "author", "contributors", "maintainers", "type", "imports", "exports", "main",
+    "module", "browser", "unpkg", "jsdelivr", "types", "typings", "typesVersions",
+    "bin", "man", "files", "directories", "scripts", "config", "sideEffects",
+    "workspaces", "engines", "engineStrict", "os", "cpu", "packageManager",
+    "publishConfig", "dependencies", "devDependencies", "peerDependencies",
+    "peerDependenciesMeta", "optionalDependencies", "bundledDependencies",
+    "bundleDependencies", "overrides", "resolutions",
+]
+
+# Within package.json, these object values keep their original key order.
+PRESERVE_ORDER_FIELDS = {"scripts"}
+
+_INDENT_RE = re.compile(r'\n([ \t]+)["\]{}]')
+
+
+def detect_indent(text):
+    """Detect the indentation of an existing JSON document. Returns a space
+    count, the string "\\t", or 2."""
+    m = _INDENT_RE.search(text)
+    if not m:
+        return 2
+    return "\t" if m.group(1)[0] == "\t" else len(m.group(1))
+
+
+def order_package_keys(keys):
+    """Return package.json keys in conventional order: known fields first (in
+    canonical sequence), then unknown fields alphabetically."""
+    known = set(PACKAGE_FIELD_ORDER)
+    present = [k for k in PACKAGE_FIELD_ORDER if k in keys]
+    unknown = sorted(k for k in keys if k not in known)
+    return present + unknown
+
+
+def sort_value(value, opts, package_top):
+    """Recursively produce a key-sorted copy of ``value``."""
+    if isinstance(value, list):
+        return [sort_value(v, opts, False) for v in value]
+    if not isinstance(value, dict):
+        return value
+
+    keys = list(value.keys())
+    if package_top and not opts.get("allKeys"):
+        ordered = order_package_keys(keys)
+    else:
+        ordered = sorted(keys)
+
+    out = {}
+    for k in ordered:
+        preserve = package_top and not opts.get("sortScripts") and k in PRESERVE_ORDER_FIELDS
+        out[k] = value[k] if preserve else sort_value(value[k], opts, False)
+    return out
+
+
+def serialize(value, indent):
+    """Serialize matching the Node port: given indent, ``: `` / ``,`` separators,
+    UTF-8 (no \\uXXXX escaping)."""
+    return json.dumps(value, indent=indent, ensure_ascii=False, separators=(",", ": "))
+
+
+def process(text, opts=None):
+    """Sort one JSON document. Returns ``{"output": str, "changed": bool}``.
+    Raises ValueError (via json) on invalid JSON."""
+    opts = opts or {}
+    data = json.loads(text)
+    indent = opts["indent"] if opts.get("indent") is not None else detect_indent(text)
+    package_top = bool(opts.get("packageJson")) and isinstance(data, dict)
+    sorted_data = sort_value(data, {"sortScripts": bool(opts.get("sortScripts")),
+                                    "allKeys": bool(opts.get("allKeys"))}, package_top)
+    output = serialize(sorted_data, indent)
+    if text.endswith("\n"):
+        output += "\n"
+    return {"output": output, "changed": output != text}

keytidy-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: keytidy
+Version: 0.1.0
+Summary: Tidy JSON key order — and sort package.json the conventional way (canonical field order, sorted dependencies, untouched scripts). Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/keytidy-py
+Project-URL: Repository, https://github.com/jjdoor/keytidy-py
+Project-URL: Issues, https://github.com/jjdoor/keytidy-py/issues
+Keywords: json,package.json,sort,format,formatter,tidy,keys,cli,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# keytidy
+
+**Tidy JSON key order — and sort `package.json` the way it's actually meant to
+look.** Inconsistent key order is pure diff noise: one teammate's editor writes
+`name` first, another's tool writes it last, and every PR churns lines that
+didn't really change. keytidy gives every JSON file one deterministic order.
+**Zero dependencies** (pure standard library).
+
+```bash
+pip install keytidy
+
+keytidy                 # sort ./package.json in place
+keytidy --check         # CI gate: exit 1 if anything isn't sorted
+```
+
+## It's not just "sort all the keys"
+
+Sorting `package.json` alphabetically would be *wrong* — `name` belongs at the
+top, not wedged between `module` and `optionalDependencies`. So keytidy treats
+`package.json` specially:
+
+- **Top-level fields** follow the conventional order (`name`, `version`,
+  `description`, …, `scripts`, `dependencies`, `devDependencies`, …). Unknown
+  fields (your `tool.*`, custom keys) sort alphabetically after the known ones.
+- **Dependency blocks** (`dependencies`, `devDependencies`, `peerDependencies`,
+  …) are sorted A→Z — the part you actually want sorted.
+- **`scripts` is left in your order**, because script order is frequently
+  meaningful (`pretest` → `test` → `posttest`, ordered build steps). Opt in with
+  `--sort-scripts` if you disagree.
+
+Every other `.json` file just gets a clean recursive alphabetical sort, with
+**arrays left in their original order** (an array is data, not config).
+
+## Example
+
+```jsonc
+// before
+{ "version": "1.0.0", "scripts": { "test": "…", "build": "…" },
+  "name": "demo", "dependencies": { "zod": "…", "axios": "…" } }
+
+// after  →  keytidy
+{
+  "name": "demo",
+  "version": "1.0.0",
+  "scripts": { "test": "…", "build": "…" },        // order preserved
+  "dependencies": { "axios": "…", "zod": "…" }      // sorted A→Z
+}
+```
+
+## Usage
+
+```bash
+keytidy                    # sort ./package.json in place
+keytidy package.json tsconfig.json
+keytidy *.json             # your shell expands the glob
+keytidy --check            # don't write; exit 1 if any file isn't sorted
+keytidy --stdout pkg.json  # print the sorted result instead of writing
+keytidy --indent 4         # force 4-space indent (default: detected, else 2)
+keytidy --sort-scripts     # also sort the package.json scripts block
+keytidy --all-keys         # ignore the conventional order, sort A→Z
+```
+
+You can also run it as a module: `python -m keytidy`.
+
+Indentation is **detected from the file** and preserved, so keytidy doesn't
+fight your existing 2-space / 4-space / tab style. The trailing newline is kept
+as-is.
+
+### As a CI / pre-commit gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: keytidy
+      name: keytidy
+      entry: keytidy --check
+      language: system
+      files: package\.json$
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | sorted (write mode) or everything already sorted (`--check`) |
+| `1` | a file needs sorting (`--check` only) |
+| `2` | invalid JSON, or a file couldn't be read/written |
+
+## Notes
+
+- It rewrites by parsing and re-serializing, so it normalizes JSON formatting.
+  It does **not** support comments or trailing commas (JSONC / `tsconfig.json`
+  with comments will report invalid JSON rather than mangle them).
+- The sort itself is pure and deterministic, shared with the Node port — for
+  typical config files the two produce identical output.
+
+## Also available for Node
+
+Same behavior, same flags: [`npx keytidy`](https://www.npmjs.com/package/keytidy)
+(source: [keytidy](https://github.com/jjdoor/keytidy)).
+
+## License
+
+MIT

keytidy-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+keytidy/__init__.py,sha256=85EiN65DqHOEbsNMm-jxMRRg2dc10O0N33E1mOIG9dc,115
+keytidy/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+keytidy/cli.py,sha256=xViDPU4C5O8xxMXuGBMmg2yDMpaSAIxROsLWfbYuoMs,5252
+keytidy/core.py,sha256=bY1Slr4mNs7DoASL_rd4hTMiUtUEDIbeuU1egAeBs8o,3959
+keytidy-0.1.0.dist-info/licenses/LICENSE,sha256=7tATQ4lC-u80SOBmjSE2cdUMyuYdG90m0E1qQLDrAaw,1077
+keytidy-0.1.0.dist-info/METADATA,sha256=1KYzjZfmfbOzeLyguq7KHyQAazKiC3or5fulkhAitCY,4590
+keytidy-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+keytidy-0.1.0.dist-info/entry_points.txt,sha256=JCC7TD_QcqY2angzyaUWZb1WFHLq9T7L_7tUdzcPCx0,45
+keytidy-0.1.0.dist-info/top_level.txt,sha256=LJdwW5-UOt5Dg0-NtRIiUpcYLeqUt-c6yl7PAromCwo,8
+keytidy-0.1.0.dist-info/RECORD,,

keytidy-0.1.0.dist-info/WHEEL

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

keytidy-0.1.0.dist-info/entry_points.txt

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

keytidy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytidy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keytidy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+keytidy