scadfmt 0.1.0__tar.gz

scadfmt-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: scadfmt
+Version: 0.1.0
+Summary: Opinionated formatter for OpenSCAD code
+Author-email: Patrick Pötz <kellervater@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kellerlabs/homeracker
+Project-URL: Repository, https://github.com/kellerlabs/homeracker
+Project-URL: Documentation, https://github.com/kellerlabs/homeracker/tree/main/cmd/scadfmt
+Project-URL: Issues, https://github.com/kellerlabs/homeracker/issues
+Project-URL: Changelog, https://github.com/kellerlabs/homeracker/blob/main/cmd/scadfmt/CHANGELOG.md
+Keywords: openscad,formatter,scad,code-style,pre-commit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 🎨 scadfmt
+
+## 📌 What
+
+An opinionated formatter for OpenSCAD code. It fixes indentation and spacing, puts blocks and statements on their own lines, and never joins lines or changes what the code does.
+
+## 🤔 Why
+
+Community contributions need one code style without style debates in review. Existing formatters rewrite code they do not understand (dropping operators, breaking `include` paths) or join hand-wrapped lines into very long ones. scadfmt only needs to know OpenSCAD's tokens, so new syntax rarely affects it, and it refuses to write output whose tokens differ from the input. See [build-own-openscad-formatter-scadfmt](../../docs/decisions/build-own-openscad-formatter-scadfmt.md).
+
+## 🔧 How
+
+### 📦 Install
+
+Requires Python 3.11 or newer, no other dependencies.
+
+```bash
+pip install scadfmt           # from PyPI
+pip install -e cmd/scadfmt    # from this repo
+```
+
+### ▶️ Usage
+
+```bash
+scadfmt format models/                  # format files in place, directories recursively
+scadfmt format --check models/          # write nothing, exit 1 if a file would change
+scadfmt format --diff part.scad         # write nothing, print a diff
+scadfmt format - < in.scad > out.scad   # stdin to stdout
+```
+
+Exit codes: `0` clean, `1` files would change (`--check`), `2` error. On an error (unknown character, unbalanced brackets) the file stays untouched.
+
+### 👀 Before and After
+
+```openscad
+include<BOSL2/std.scad>
+wall=2;// wall strength
+height_units=3; // rack units
+/**
+ * Bracket holding a device of the given size.
+ * center: centers the body on the origin
+ */
+module bracket(width=10,depth=20,center=false){
+    size=[width,depth,wall*height_units];
+    if(center){translate(-size/2)cube(size);}else{cube(size);}
+    for(i=[0:2:width])
+    translate([i,0,0])
+    rotate([0,0,-90])
+    #cylinder(h=wall,r=1);
+}
+```
+
+becomes
+
+```openscad
+include <BOSL2/std.scad>
+
+wall = 2;          // wall strength
+height_units = 3;  // rack units
+
+/**
+ * Bracket holding a device of the given size.
+ * center: centers the body on the origin
+ */
+module bracket(width = 10, depth = 20, center = false) {
+  size = [width, depth, wall * height_units];
+  if (center) {
+    translate(-size / 2) cube(size);
+  } else {
+    cube(size);
+  }
+  for (i = [0:2:width])
+    translate([i, 0, 0])
+      rotate([0, 0, -90])
+        #cylinder(h = wall, r = 1);
+}
+```
+
+### 📏 Rules
+
+| Rule | Example |
+|---|---|
+| 2 spaces per open `{ ( [`, one level per line that opens them | `cube([`↵`  1,`↵`]);` |
+| A line continuing a module call nests one level further | `translate(v)`↵`  cube();` |
+| A line continuing an expression is one level in | `x =`↵`  a +`↵`  b;` |
+| Spaces around every binary operator and every `=` | `cube(size = w * 2, center = true);` |
+| Tight unary operators, modifiers, calls, indexing | `-x`, `!a`, `#cube()`, `f(a)[0]` |
+| Tight range colons, spaced ternary colons | `[0:2:10]`, `a ? b : c` |
+| `if`, `for`, `intersection_for`, `function` get a space before `(` | `for (i = [0:2])` |
+| Space after commas, none inside brackets | `f(a, [1, 2])` |
+| Block contents on their own lines, `}` on its own line except `} else`, empty `{}` stays | `if (a) {`↵`  b();`↵`} else {` |
+| One statement per line (`;` inside `for (...)` excepted) | `a();`↵`b();` |
+| Exactly one blank line before and after each `module` and `function` definition, none next to a brace | `x = 1;`↵↵`module m() {` |
+| Imports form one block without blank lines, followed by exactly one blank line | `include <a.scad>`↵`use <b.scad>`↵↵`x = 1;` |
+| Trailing comments on consecutive lines share one column, a lone one gets 2 spaces | `x = 1;  // note` |
+| At most 2 blank lines at top level, 1 inside blocks | |
+| Keeps the file's line endings (LF or CRLF, judged by the first one), no trailing whitespace, one final newline | |
+
+Comments (`//` or `/* */`) directly above a line belong to it, so a blank line added before that line goes above its comments. Lines are never joined and line length is never limited.
+
+### 🙈 Opting Out
+
+Lines between `// fmt: off` and `// fmt: on` stay as written, for example a hand-aligned matrix:
+
+```openscad
+// fmt: off
+identity = [
+  1, 0, 0,
+  0, 1, 0,
+];
+// fmt: on
+```
+
+### 🪝 Pre-commit
+
+In another repository, install scadfmt from PyPI through a local hook:
+
+```yaml
+- repo: local
+  hooks:
+    - id: scadfmt
+      name: scadfmt
+      entry: scadfmt format
+      language: python
+      additional_dependencies: [scadfmt==0.1.0]
+      files: \.scad$
+```
+
+### 🖥️ VS Code
+
+```bash
+scadfmt vscode
+```
+
+Installs the [Custom Local Formatters](https://marketplace.visualstudio.com/items?itemName=jkillian.custom-local-formatters) extension and makes scadfmt the default formatter for `.scad` files in `.vscode/settings.json`, so **Format Document** (`Shift+Alt+F`) runs it. It refuses to touch a `settings.json` with comments; add the settings by hand then:
+
+```jsonc
+"customLocalFormatters.formatters": [{ "command": "\"/path/to/python\" -m scadfmt format -", "languages": ["scad"] }],
+"[scad]": { "editor.defaultFormatter": "jkillian.custom-local-formatters" }
+```
+
+For formatting on save, add `"editor.formatOnSave": true` to the `[scad]` block.
+
+### 🧪 Tests
+
+See [TESTING.md](../../TESTING.md#scadfmt-tests). `tests/canary/` holds a file using every OpenSCAD construct and its expected output; `check.sh` checks both against the pinned OpenSCAD.
+
+## 📚 References
+
+- [#177](https://github.com/kellerlabs/homeracker/issues/177): introduce an OpenSCAD formatter
+- [build-own-openscad-formatter-scadfmt](../../docs/decisions/build-own-openscad-formatter-scadfmt.md): why scadfmt exists and how it works
+- [OpenSCAD language reference](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language)

scadfmt-0.1.0/README.md

@@ -0,0 +1,152 @@
+# 🎨 scadfmt
+
+## 📌 What
+
+An opinionated formatter for OpenSCAD code. It fixes indentation and spacing, puts blocks and statements on their own lines, and never joins lines or changes what the code does.
+
+## 🤔 Why
+
+Community contributions need one code style without style debates in review. Existing formatters rewrite code they do not understand (dropping operators, breaking `include` paths) or join hand-wrapped lines into very long ones. scadfmt only needs to know OpenSCAD's tokens, so new syntax rarely affects it, and it refuses to write output whose tokens differ from the input. See [build-own-openscad-formatter-scadfmt](../../docs/decisions/build-own-openscad-formatter-scadfmt.md).
+
+## 🔧 How
+
+### 📦 Install
+
+Requires Python 3.11 or newer, no other dependencies.
+
+```bash
+pip install scadfmt           # from PyPI
+pip install -e cmd/scadfmt    # from this repo
+```
+
+### ▶️ Usage
+
+```bash
+scadfmt format models/                  # format files in place, directories recursively
+scadfmt format --check models/          # write nothing, exit 1 if a file would change
+scadfmt format --diff part.scad         # write nothing, print a diff
+scadfmt format - < in.scad > out.scad   # stdin to stdout
+```
+
+Exit codes: `0` clean, `1` files would change (`--check`), `2` error. On an error (unknown character, unbalanced brackets) the file stays untouched.
+
+### 👀 Before and After
+
+```openscad
+include<BOSL2/std.scad>
+wall=2;// wall strength
+height_units=3; // rack units
+/**
+ * Bracket holding a device of the given size.
+ * center: centers the body on the origin
+ */
+module bracket(width=10,depth=20,center=false){
+    size=[width,depth,wall*height_units];
+    if(center){translate(-size/2)cube(size);}else{cube(size);}
+    for(i=[0:2:width])
+    translate([i,0,0])
+    rotate([0,0,-90])
+    #cylinder(h=wall,r=1);
+}
+```
+
+becomes
+
+```openscad
+include <BOSL2/std.scad>
+
+wall = 2;          // wall strength
+height_units = 3;  // rack units
+
+/**
+ * Bracket holding a device of the given size.
+ * center: centers the body on the origin
+ */
+module bracket(width = 10, depth = 20, center = false) {
+  size = [width, depth, wall * height_units];
+  if (center) {
+    translate(-size / 2) cube(size);
+  } else {
+    cube(size);
+  }
+  for (i = [0:2:width])
+    translate([i, 0, 0])
+      rotate([0, 0, -90])
+        #cylinder(h = wall, r = 1);
+}
+```
+
+### 📏 Rules
+
+| Rule | Example |
+|---|---|
+| 2 spaces per open `{ ( [`, one level per line that opens them | `cube([`↵`  1,`↵`]);` |
+| A line continuing a module call nests one level further | `translate(v)`↵`  cube();` |
+| A line continuing an expression is one level in | `x =`↵`  a +`↵`  b;` |
+| Spaces around every binary operator and every `=` | `cube(size = w * 2, center = true);` |
+| Tight unary operators, modifiers, calls, indexing | `-x`, `!a`, `#cube()`, `f(a)[0]` |
+| Tight range colons, spaced ternary colons | `[0:2:10]`, `a ? b : c` |
+| `if`, `for`, `intersection_for`, `function` get a space before `(` | `for (i = [0:2])` |
+| Space after commas, none inside brackets | `f(a, [1, 2])` |
+| Block contents on their own lines, `}` on its own line except `} else`, empty `{}` stays | `if (a) {`↵`  b();`↵`} else {` |
+| One statement per line (`;` inside `for (...)` excepted) | `a();`↵`b();` |
+| Exactly one blank line before and after each `module` and `function` definition, none next to a brace | `x = 1;`↵↵`module m() {` |
+| Imports form one block without blank lines, followed by exactly one blank line | `include <a.scad>`↵`use <b.scad>`↵↵`x = 1;` |
+| Trailing comments on consecutive lines share one column, a lone one gets 2 spaces | `x = 1;  // note` |
+| At most 2 blank lines at top level, 1 inside blocks | |
+| Keeps the file's line endings (LF or CRLF, judged by the first one), no trailing whitespace, one final newline | |
+
+Comments (`//` or `/* */`) directly above a line belong to it, so a blank line added before that line goes above its comments. Lines are never joined and line length is never limited.
+
+### 🙈 Opting Out
+
+Lines between `// fmt: off` and `// fmt: on` stay as written, for example a hand-aligned matrix:
+
+```openscad
+// fmt: off
+identity = [
+  1, 0, 0,
+  0, 1, 0,
+];
+// fmt: on
+```
+
+### 🪝 Pre-commit
+
+In another repository, install scadfmt from PyPI through a local hook:
+
+```yaml
+- repo: local
+  hooks:
+    - id: scadfmt
+      name: scadfmt
+      entry: scadfmt format
+      language: python
+      additional_dependencies: [scadfmt==0.1.0]
+      files: \.scad$
+```
+
+### 🖥️ VS Code
+
+```bash
+scadfmt vscode
+```
+
+Installs the [Custom Local Formatters](https://marketplace.visualstudio.com/items?itemName=jkillian.custom-local-formatters) extension and makes scadfmt the default formatter for `.scad` files in `.vscode/settings.json`, so **Format Document** (`Shift+Alt+F`) runs it. It refuses to touch a `settings.json` with comments; add the settings by hand then:
+
+```jsonc
+"customLocalFormatters.formatters": [{ "command": "\"/path/to/python\" -m scadfmt format -", "languages": ["scad"] }],
+"[scad]": { "editor.defaultFormatter": "jkillian.custom-local-formatters" }
+```
+
+For formatting on save, add `"editor.formatOnSave": true` to the `[scad]` block.
+
+### 🧪 Tests
+
+See [TESTING.md](../../TESTING.md#scadfmt-tests). `tests/canary/` holds a file using every OpenSCAD construct and its expected output; `check.sh` checks both against the pinned OpenSCAD.
+
+## 📚 References
+
+- [#177](https://github.com/kellerlabs/homeracker/issues/177): introduce an OpenSCAD formatter
+- [build-own-openscad-formatter-scadfmt](../../docs/decisions/build-own-openscad-formatter-scadfmt.md): why scadfmt exists and how it works
+- [OpenSCAD language reference](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language)

scadfmt-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scadfmt"
+version = "0.1.0"
+description = "Opinionated formatter for OpenSCAD code"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "Patrick Pötz", email = "kellervater@gmail.com"}
+]
+keywords = ["openscad", "formatter", "scad", "code-style", "pre-commit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/kellerlabs/homeracker"
+Repository = "https://github.com/kellerlabs/homeracker"
+Documentation = "https://github.com/kellerlabs/homeracker/tree/main/cmd/scadfmt"
+Issues = "https://github.com/kellerlabs/homeracker/issues"
+Changelog = "https://github.com/kellerlabs/homeracker/blob/main/cmd/scadfmt/CHANGELOG.md"
+
+[project.scripts]
+scadfmt = "scadfmt.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scadfmt*"]
+
+[tool.setuptools.package-data]
+scadfmt = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+# With PYTHONWARNDEFAULTENCODING=1, text I/O without an explicit encoding fails (breaks on non-UTF-8 Windows locales).
+filterwarnings = ["error::EncodingWarning"]
+
+[tool.coverage.run]
+source = ["scadfmt"]
+omit = ["scadfmt/__main__.py"]
+branch = true
+
+[tool.coverage.report]
+# Raise when coverage grows, never lower.
+fail_under = 98
+show_missing = true
+skip_covered = true
+exclude_also = [
+    "if __name__ == .__main__.:",
+]

scadfmt-0.1.0/scadfmt/__init__.py

@@ -0,0 +1,9 @@
+"""Opinionated formatter for OpenSCAD code (scadfmt)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# release-please bumps pyproject.toml only, so the installed metadata is the single source of truth.
+try:
+    __version__ = version("scadfmt")
+except PackageNotFoundError:
+    __version__ = "unknown"

scadfmt-0.1.0/scadfmt/__main__.py

@@ -0,0 +1,7 @@
+"""Run scadfmt as `python -m scadfmt`."""
+
+import sys
+
+from scadfmt.cli import main
+
+sys.exit(main())

scadfmt-0.1.0/scadfmt/cli.py

@@ -0,0 +1,147 @@
+"""Command-line interface for scadfmt."""
+
+import argparse
+import difflib
+import logging
+import sys
+from pathlib import Path
+
+from scadfmt import __version__
+from scadfmt.fileio import write_atomically
+from scadfmt.formatter import FormatError, format_source
+from scadfmt.vscode import setup_vscode
+
+logger = logging.getLogger(__name__)
+
+EXIT_OK = 0
+EXIT_CHANGES = 1
+EXIT_ERROR = 2
+
+
+def _collect(paths: list[str]) -> list[Path]:
+    """Expand directories to the .scad files below them, sorted."""
+    files: list[Path] = []
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            files.extend(sorted(path.rglob("*.scad")))
+        else:
+            files.append(path)
+    return files
+
+
+def _diff(before: str, after: str, name: str) -> str:
+    """Unified diff between two versions of a file."""
+    return "".join(
+        difflib.unified_diff(
+            before.splitlines(keepends=True),
+            after.splitlines(keepends=True),
+            f"{name} (original)",
+            f"{name} (formatted)",
+        )
+    )
+
+
+def _write(text: str) -> None:
+    """Write UTF-8 text to stdout without newline translation."""
+    sys.stdout.buffer.write(text.encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
+def _format_stdin(check: bool, diff: bool) -> int:
+    """Format stdin to stdout, or report on it with --check or --diff."""
+    # Bytes, not text: text mode would translate newlines and use the locale codepage on Windows.
+    try:
+        source = sys.stdin.buffer.read().decode("utf-8")
+        formatted = format_source(source)
+    except (UnicodeDecodeError, FormatError) as e:
+        logger.error("<stdin>:%s", e)
+        return EXIT_ERROR
+    if diff:
+        _write(_diff(source, formatted, "<stdin>"))
+    elif not check:
+        _write(formatted)
+    return EXIT_CHANGES if check and formatted != source else EXIT_OK
+
+
+def _format_files(files: list[Path], check: bool, diff: bool) -> int:
+    """Format files in place, or report on them with --check or --diff."""
+    changed = errors = 0
+    for path in files:
+        try:
+            source = path.read_bytes().decode("utf-8")
+            formatted = format_source(source)
+        except (OSError, UnicodeDecodeError, FormatError) as e:
+            logger.error("%s:%s", path, e)
+            errors += 1
+            continue
+        if formatted == source:
+            continue
+        changed += 1
+        if diff:
+            _write(_diff(source, formatted, str(path)))
+        if check or diff:
+            logger.info("would reformat %s", path)
+        else:
+            try:
+                write_atomically(path, formatted)
+            except OSError as e:
+                logger.error("%s: cannot write: %s", path, e)
+                errors += 1
+                continue
+            logger.info("reformatted %s", path)
+    if errors:
+        return EXIT_ERROR
+    return EXIT_CHANGES if check and changed else EXIT_OK
+
+
+def _handle_format(args: argparse.Namespace) -> int:
+    """Run the format subcommand."""
+    if args.paths == ["-"]:
+        return _format_stdin(args.check, args.diff)
+    if "-" in args.paths:
+        logger.error("'-' (stdin) cannot be combined with file paths")
+        return EXIT_ERROR
+    return _format_files(_collect(args.paths), args.check, args.diff)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser.
+
+    Returns:
+        The configured parser.
+    """
+    parser = argparse.ArgumentParser(prog="scadfmt", description="Opinionated formatter for OpenSCAD code.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    format_parser = subparsers.add_parser("format", help="Format .scad files in place")
+    format_parser.add_argument("paths", nargs="+", help="Files or directories to format, or '-' for stdin")
+    format_parser.add_argument("--check", action="store_true", help="Write nothing, exit 1 if any file would change")
+    format_parser.add_argument("--diff", action="store_true", help="Write nothing, print a diff of the changes")
+
+    vscode_parser = subparsers.add_parser("vscode", help="Make scadfmt the VS Code formatter for .scad files")
+    vscode_parser.add_argument(
+        "--workspace", default=".", help="Workspace folder whose .vscode/settings.json is updated (default: .)"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run scadfmt.
+
+    Args:
+        argv: Arguments without the program name. Defaults to sys.argv[1:].
+
+    Returns:
+        Exit code: 0 clean, 1 files would change (--check), 2 error.
+    """
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    args = build_parser().parse_args(argv)
+    if args.command == "vscode":
+        return EXIT_OK if setup_vscode(Path(args.workspace)) else EXIT_ERROR
+    return _handle_format(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scadfmt-0.1.0/scadfmt/fileio.py

@@ -0,0 +1,31 @@
+"""Atomic file writes shared by formatting and VS Code setup."""
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+
+def write_atomically(path: Path, text: str) -> None:
+    """Replace the file at path with text in one step, so a failed write never leaves a truncated file.
+
+    A symlink is followed and its target updated. An existing file keeps its permissions.
+
+    Args:
+        path: File to write, created if missing.
+        text: New content, written as UTF-8 without newline translation.
+
+    Raises:
+        OSError: If the temporary file cannot be written or moved into place.
+    """
+    target = path.resolve() if path.is_symlink() else path
+    handle, temp_name = tempfile.mkstemp(dir=target.parent, prefix=f".{target.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(handle, "wb") as temp:
+            temp.write(text.encode("utf-8"))
+        if target.exists():
+            shutil.copymode(target, temp_name)
+        os.replace(temp_name, target)
+    except OSError:
+        Path(temp_name).unlink(missing_ok=True)
+        raise