true-formatter 0.1.0__tar.gz

true_formatter-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

true_formatter-0.1.0/setup.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from setuptools import find_packages, setup
+
+
+ROOT = Path(__file__).parent
+README = (ROOT / "README.md").read_text(encoding="utf-8")
+
+
+setup(
+    name="true-formatter",
+    version="0.1.0",
+    description="The uncompromising Python formatter.",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    license="MIT",
+    author="True Contributors",
+    python_requires=">=3.8",
+    packages=find_packages(include=["true_formatter", "true_formatter.*"]),
+    include_package_data=True,
+    install_requires=[],
+    extras_require={
+        "dev": [
+            "pytest>=7.4",
+            "pytest-cov>=4.1",
+        ]
+    },
+    entry_points={
+        "console_scripts": [
+            "true=true_formatter.cli:main",
+        ]
+    },
+)

true_formatter-0.1.0/tests/test_cli.py

@@ -0,0 +1,79 @@
+"""Tests for true_formatter.cli — command-line interface."""
+
+from __future__ import annotations
+
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import pytest
+from pathlib import Path
+from true_formatter.cli import main, build_parser
+
+
+class TestBuildParser:
+    def test_returns_parser(self):
+        import argparse
+        p = build_parser()
+        assert isinstance(p, argparse.ArgumentParser)
+
+    def test_default_line_length(self):
+        p = build_parser()
+        args = p.parse_args([])
+        assert args.line_length == 88
+
+    def test_custom_line_length(self):
+        p = build_parser()
+        args = p.parse_args(["-l", "79"])
+        assert args.line_length == 79
+
+    def test_check_flag(self):
+        p = build_parser()
+        args = p.parse_args(["--check", "file.py"])
+        assert args.check is True
+
+    def test_skip_string_normalization_flag(self):
+        p = build_parser()
+        args = p.parse_args(["-S", "file.py"])
+        assert args.skip_string_normalization is True
+
+
+class TestMainNoArgs:
+    def test_no_src_returns_zero(self):
+        code = main([])
+        assert code == 0
+
+
+class TestMainWithFile:
+    def test_check_formatted_file(self, tmp_path: Path):
+        f = tmp_path / "ok.py"
+        f.write_text("x = 1\n", encoding="utf-8")
+        code = main(["--check", str(f)])
+        assert code == 0
+
+    def test_check_unformatted_file(self, tmp_path: Path):
+        f = tmp_path / "bad.py"
+        f.write_text("x=1\n", encoding="utf-8")
+        code = main(["--check", str(f)])
+        # May be 0 or 1 depending on formatter output — just check it runs
+        assert isinstance(code, int)
+
+    def test_format_in_place(self, tmp_path: Path):
+        f = tmp_path / "src.py"
+        f.write_text("x = 1   \n", encoding="utf-8")
+        main([str(f)])
+        result = f.read_text(encoding="utf-8")
+        assert not any(line.endswith("   ") for line in result.splitlines())
+
+    def test_diff_flag(self, tmp_path: Path, capsys):
+        f = tmp_path / "diff.py"
+        f.write_text("x=1\n", encoding="utf-8")
+        main(["--diff", str(f)])
+        # Test just that it doesn't crash
+
+
+class TestMainDirectory:
+    def test_processes_py_files_in_dir(self, tmp_path: Path):
+        (tmp_path / "a.py").write_text("x = 1\n", encoding="utf-8")
+        (tmp_path / "b.py").write_text("y = 2\n", encoding="utf-8")
+        code = main(["--check", str(tmp_path)])
+        assert code == 0

true_formatter-0.1.0/tests/test_core.py

@@ -0,0 +1,110 @@
+"""Tests for true_formatter.core — format_str, format_file_contents, check_format."""
+
+from __future__ import annotations
+
+import pytest
+
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import true_formatter
+from true_formatter import Mode, format_str, format_file_contents, check_format
+from true_formatter.exceptions import TrueFormattingError
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# format_str
+# ──────────────────────────────────────────────────────────────────────────────
+
+class TestFormatStr:
+    def test_returns_string(self):
+        result = format_str("x = 1\n", mode=Mode())
+        assert isinstance(result, str)
+
+    def test_already_formatted_unchanged(self):
+        src = "x = 1\n"
+        assert format_str(src, mode=Mode()) == src
+
+    def test_trailing_whitespace_removed(self):
+        src = "x = 1   \n"
+        result = format_str(src, mode=Mode())
+        assert "   " not in result
+
+    def test_type_error_on_non_string(self):
+        with pytest.raises(TypeError):
+            format_str(42, mode=Mode())  # type: ignore[arg-type]
+
+    def test_empty_string(self):
+        result = format_str("", mode=Mode())
+        assert isinstance(result, str)
+
+    def test_comment_only(self):
+        src = "# just a comment\n"
+        result = format_str(src, mode=Mode())
+        assert "# just a comment" in result
+
+    def test_multiline_preserved(self):
+        src = "x = 1\ny = 2\n"
+        result = format_str(src, mode=Mode())
+        assert "x" in result
+        assert "y" in result
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# format_file_contents
+# ──────────────────────────────────────────────────────────────────────────────
+
+class TestFormatFileContents:
+    def test_ensures_trailing_newline(self):
+        result = format_file_contents("x = 1", mode=Mode())
+        assert result.endswith("\n")
+
+    def test_does_not_double_newline(self):
+        result = format_file_contents("x = 1\n", mode=Mode())
+        assert result == result.rstrip("\n") + "\n"
+
+    def test_empty_file(self):
+        result = format_file_contents("", mode=Mode())
+        assert result.endswith("\n")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# check_format
+# ──────────────────────────────────────────────────────────────────────────────
+
+class TestCheckFormat:
+    def test_already_formatted(self):
+        src = format_file_contents("x = 1\n", mode=Mode())
+        assert check_format(src, mode=Mode()) is True
+
+    def test_trailing_space_detected(self):
+        src = "x = 1   \n"
+        assert check_format(src, mode=Mode()) is False
+
+    def test_empty_string(self):
+        # empty string is not formatted (no trailing newline) — implementation detail
+        result = check_format("", mode=Mode())
+        assert isinstance(result, bool)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Mode
+# ──────────────────────────────────────────────────────────────────────────────
+
+class TestMode:
+    def test_default_line_length(self):
+        assert Mode().line_length == 88
+
+    def test_default_string_normalization(self):
+        assert Mode().string_normalization is True
+
+    def test_quote_char_double_by_default(self):
+        assert Mode().quote_char == '"'
+
+    def test_quote_char_single_when_skip(self):
+        m = Mode(skip_string_normalization=True)
+        assert m.quote_char == "'"
+
+    def test_custom_line_length(self):
+        m = Mode(line_length=79)
+        assert m.line_length == 79

true_formatter-0.1.0/tests/test_rules.py

@@ -0,0 +1,74 @@
+"""Tests for true_formatter.rules — RuleSet and Rule base class."""
+
+from __future__ import annotations
+
+import tokenize
+import io
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import pytest
+from true_formatter.rules import Rule, RuleSet, DEFAULT_RULES, NormaliseCommaSpacing
+from true_formatter import Mode
+
+
+def _tokenize(src: str) -> list[tokenize.TokenInfo]:
+    return list(tokenize.generate_tokens(io.StringIO(src).readline))
+
+
+class TestRuleSet:
+    def test_default_rules_non_empty(self):
+        assert len(DEFAULT_RULES) > 0
+
+    def test_add_returns_new_ruleset(self):
+        rule = NormaliseCommaSpacing()
+        new_rs = DEFAULT_RULES.add(rule)
+        assert len(new_rs) == len(DEFAULT_RULES) + 1
+        assert DEFAULT_RULES is not new_rs
+
+    def test_remove_by_name(self):
+        rs = DEFAULT_RULES.remove("comma-spacing")
+        names = [r.name for r in rs]
+        assert "comma-spacing" not in names
+
+    def test_remove_nonexistent_name_ok(self):
+        rs = DEFAULT_RULES.remove("does-not-exist")
+        assert len(rs) == len(DEFAULT_RULES)
+
+    def test_iterable(self):
+        rules = list(DEFAULT_RULES)
+        assert all(isinstance(r, Rule) for r in rules)
+
+
+class TestBuiltinRules:
+    def test_comma_spacing_passthrough(self):
+        tokens = _tokenize("x = 1\n")
+        rule = NormaliseCommaSpacing()
+        result = rule.apply(tokens, Mode())
+        assert isinstance(result, list)
+        assert len(result) == len(tokens)
+
+    def test_rule_has_name(self):
+        rule = NormaliseCommaSpacing()
+        assert isinstance(rule.name, str)
+        assert rule.name
+
+
+class TestCustomRule:
+    def test_custom_rule_applied(self):
+        class UppercaseCommentsRule(Rule):
+            name = "uppercase-comments"
+
+            def apply(self, tokens, mode):
+                out = []
+                for tok in tokens:
+                    if tok.type == tokenize.COMMENT:
+                        tok = tok._replace(string=tok.string.upper())
+                    out.append(tok)
+                return out
+
+        tokens = _tokenize("# hello\nx = 1\n")
+        rule = UppercaseCommentsRule()
+        result = rule.apply(tokens, Mode())
+        comment_tokens = [t for t in result if t.type == tokenize.COMMENT]
+        assert all(t.string == t.string.upper() for t in comment_tokens)