sectionise 0.1.1__tar.gz

sectionise-0.1.1/.env.example

@@ -0,0 +1,12 @@
+# Local publishing to PyPI. Copy this file to .env and paste your token in.
+# .env is gitignored, so the token is never committed.
+#
+#   cp .env.example .env
+#   # edit .env, then:
+#   set -a && source .env && set +a
+#   uv build && uv publish dist/*
+#
+# Create a token at https://pypi.org/manage/account/token/ (scope it to the
+# sectionise project once it exists). In CI, this same value lives in the
+# PYPI_API_TOKEN GitHub Actions secret instead.
+UV_PUBLISH_TOKEN=pypi-your-token-here

sectionise-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history + tags so hatch-vcs can read the version
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish dist/*
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}

sectionise-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.env
+.env.local
+*.pypi-token

sectionise-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+repos:
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.14.9
+      hooks:
+          - id: ruff-check
+            args: [--fix]
+            stages: [pre-commit]
+          - id: ruff-format
+            stages: [pre-commit]
+
+    - repo: https://github.com/tox-dev/pyproject-fmt
+      rev: v2.8.0
+      hooks:
+          - id: pyproject-fmt
+            stages: [pre-commit]
+
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v6.0.0
+      hooks:
+          - id: check-merge-conflict
+            stages: [pre-commit]
+          - id: end-of-file-fixer
+            stages: [pre-commit]
+          - id: trailing-whitespace
+            stages: [pre-commit]
+          - id: check-added-large-files
+            stages: [pre-commit]
+
+    # Dogfood: standardise this repo's own section headers.
+    - repo: local
+      hooks:
+          - id: sectionise
+            name: Section header banners
+            entry: sectionise
+            language: system
+            types: [text]
+            stages: [pre-commit]

sectionise-0.1.1/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: sectionise
+  name: Section header banners
+  description: >
+    Standardise section-header comment banners to one canonical style. Reads
+    settings from [tool.sectionise] in the repo's pyproject.toml; flags override.
+  entry: sectionise
+  language: python
+  types: [text]

sectionise-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

sectionise-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitchell Needham
+
+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.

sectionise-0.1.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: sectionise
+Version: 0.1.1
+Summary: Standardise section-header comment banners
+Project-URL: Homepage, https://github.com/MitchellNeedham/sectionise
+Project-URL: Repository, https://github.com/MitchellNeedham/sectionise
+Author-email: Mitchell Needham <contact@mitchellneedham.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: comments,formatter,linter,pre-commit,section-headers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# sectionise
+
+[![PyPI](https://img.shields.io/pypi/v/sectionise.svg)](https://pypi.org/project/sectionise/)
+[![Python](https://img.shields.io/pypi/pyversions/sectionise.svg)](https://pypi.org/project/sectionise/)
+
+Standardise section-header comment banners across a codebase to one canonical
+style. Runs as a pre-commit hook or a CLI, and is configured from
+`pyproject.toml` (with flag overrides).
+
+A section header is a comment styled as a banner: a title framed by a run of
+fill characters. Real code accumulates many variants; `sectionise` detects them
+and rewrites each to the same shape.
+
+## What it standardises
+
+| Variant | Example in |
+| --- | --- |
+| Single-line, framed both sides | `# ------- Loading models -------` |
+| Single-line, filled one side | `# Ancillary functions ----------` |
+| Unicode fill (em/en dash, box rules) | `# ——— Loading models ———` |
+| Three-line box | a rule line, a title comment, a rule line |
+
+All of them normalise to the configured style, for example the single-line form:
+
+```
+# ---------------------------- Loading models -----------------------------
+```
+
+Detection is conservative: only full-line comments whose content is framed by a
+fill run of at least `min_run` characters are touched. Ordinary comments,
+trailing comments, and commented-out code (`# print("=== run ===")`) are left
+alone. Title-less rules (`# --------`) are ignored unless `dividers` is enabled.
+
+A title too long to fit the chosen style is reported as an error suggesting a
+shorter title or the multi-line `box` style, rather than being silently
+overflowed.
+
+## Installation
+
+```bash
+pip install sectionise
+# or: uv add sectionise    (add to a project)
+# or: uvx sectionise ...   (run without installing)
+```
+
+## Use as a pre-commit hook
+
+```yaml
+- repo: https://github.com/MitchellNeedham/sectionise
+  rev: 0.1.0
+  hooks:
+      - id: sectionise
+```
+
+It fixes in place and fails the commit if it changed anything (re-stage and
+commit again), the same way `ruff-format` behaves.
+
+## Use as a CLI
+
+```bash
+sectionise path/to/file.py          # fix in place
+sectionise --check path/to/file.py  # report only, no writes
+```
+
+## Configuration
+
+Settings resolve with the precedence **flags > `[tool.sectionise]` > defaults**.
+Put shared settings in each repo's `pyproject.toml`:
+
+```toml
+[tool.sectionise]
+width = 88
+style = "single"        # or "box"
+fill = "-"
+detect_chars = "-=*_~#—–─═"
+min_run = 3
+require_both_sides = false
+dividers = false
+# max_title = 60        # optional hard cap on title length
+```
+
+| Setting | Flag | Default | Meaning |
+| --- | --- | --- | --- |
+| `width` | `--width` | `88` | Target total line length. |
+| `style` | `--style` | `single` | Output form: `single` line or 3-line `box`. |
+| `fill` | `--fill` | `-` | Output fill character. |
+| `detect_chars` | `--detect-chars` | `-=*_~#—–─═` | Characters recognised as fill in input. |
+| `min_run` | `--min-run` | `3` | Minimum fill-run length to count as a banner side. |
+| `require_both_sides` | `--require-both-sides` | `false` | Only treat both-sided comments as banners. |
+| `dividers` | `--dividers` | `false` | Also standardise title-less rules. |
+| `max_title` | `--max-title` | none | Hard cap on title length, on top of the width fit. |
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+```
+
+## Publishing
+
+Releases go to [PyPI](https://pypi.org/project/sectionise/) on a version tag.
+
+- **Set the token once.** In the GitHub repo, add a repository secret named
+  `PYPI_API_TOKEN` holding a PyPI API token
+  (Settings > Secrets and variables > Actions).
+- **Release.** Tag a version and push it; the publish workflow builds and
+  uploads:
+
+  ```bash
+  git tag 0.1.0
+  git push origin 0.1.0
+  ```
+
+  The version comes from the tag via `hatch-vcs`, so the tag is the single
+  source of truth.
+
+To publish from your machine instead, copy `.env.example` to `.env`, paste your
+token, and run:
+
+```bash
+set -a && source .env && set +a
+uv build && uv publish dist/*
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sectionise-0.1.1/README.md

@@ -0,0 +1,129 @@
+# sectionise
+
+[![PyPI](https://img.shields.io/pypi/v/sectionise.svg)](https://pypi.org/project/sectionise/)
+[![Python](https://img.shields.io/pypi/pyversions/sectionise.svg)](https://pypi.org/project/sectionise/)
+
+Standardise section-header comment banners across a codebase to one canonical
+style. Runs as a pre-commit hook or a CLI, and is configured from
+`pyproject.toml` (with flag overrides).
+
+A section header is a comment styled as a banner: a title framed by a run of
+fill characters. Real code accumulates many variants; `sectionise` detects them
+and rewrites each to the same shape.
+
+## What it standardises
+
+| Variant | Example in |
+| --- | --- |
+| Single-line, framed both sides | `# ------- Loading models -------` |
+| Single-line, filled one side | `# Ancillary functions ----------` |
+| Unicode fill (em/en dash, box rules) | `# ——— Loading models ———` |
+| Three-line box | a rule line, a title comment, a rule line |
+
+All of them normalise to the configured style, for example the single-line form:
+
+```
+# ---------------------------- Loading models -----------------------------
+```
+
+Detection is conservative: only full-line comments whose content is framed by a
+fill run of at least `min_run` characters are touched. Ordinary comments,
+trailing comments, and commented-out code (`# print("=== run ===")`) are left
+alone. Title-less rules (`# --------`) are ignored unless `dividers` is enabled.
+
+A title too long to fit the chosen style is reported as an error suggesting a
+shorter title or the multi-line `box` style, rather than being silently
+overflowed.
+
+## Installation
+
+```bash
+pip install sectionise
+# or: uv add sectionise    (add to a project)
+# or: uvx sectionise ...   (run without installing)
+```
+
+## Use as a pre-commit hook
+
+```yaml
+- repo: https://github.com/MitchellNeedham/sectionise
+  rev: 0.1.0
+  hooks:
+      - id: sectionise
+```
+
+It fixes in place and fails the commit if it changed anything (re-stage and
+commit again), the same way `ruff-format` behaves.
+
+## Use as a CLI
+
+```bash
+sectionise path/to/file.py          # fix in place
+sectionise --check path/to/file.py  # report only, no writes
+```
+
+## Configuration
+
+Settings resolve with the precedence **flags > `[tool.sectionise]` > defaults**.
+Put shared settings in each repo's `pyproject.toml`:
+
+```toml
+[tool.sectionise]
+width = 88
+style = "single"        # or "box"
+fill = "-"
+detect_chars = "-=*_~#—–─═"
+min_run = 3
+require_both_sides = false
+dividers = false
+# max_title = 60        # optional hard cap on title length
+```
+
+| Setting | Flag | Default | Meaning |
+| --- | --- | --- | --- |
+| `width` | `--width` | `88` | Target total line length. |
+| `style` | `--style` | `single` | Output form: `single` line or 3-line `box`. |
+| `fill` | `--fill` | `-` | Output fill character. |
+| `detect_chars` | `--detect-chars` | `-=*_~#—–─═` | Characters recognised as fill in input. |
+| `min_run` | `--min-run` | `3` | Minimum fill-run length to count as a banner side. |
+| `require_both_sides` | `--require-both-sides` | `false` | Only treat both-sided comments as banners. |
+| `dividers` | `--dividers` | `false` | Also standardise title-less rules. |
+| `max_title` | `--max-title` | none | Hard cap on title length, on top of the width fit. |
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+```
+
+## Publishing
+
+Releases go to [PyPI](https://pypi.org/project/sectionise/) on a version tag.
+
+- **Set the token once.** In the GitHub repo, add a repository secret named
+  `PYPI_API_TOKEN` holding a PyPI API token
+  (Settings > Secrets and variables > Actions).
+- **Release.** Tag a version and push it; the publish workflow builds and
+  uploads:
+
+  ```bash
+  git tag 0.1.0
+  git push origin 0.1.0
+  ```
+
+  The version comes from the tag via `hatch-vcs`, so the tag is the single
+  source of truth.
+
+To publish from your machine instead, copy `.env.example` to `.env`, paste your
+token, and run:
+
+```bash
+set -a && source .env && set +a
+uv build && uv publish dist/*
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sectionise-0.1.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = [ "hatch-vcs", "hatchling" ]
+
+[project]
+name = "sectionise"
+description = "Standardise section-header comment banners"
+readme = "README.md"
+license = "MIT"
+authors = [ { name = "Mitchell Needham", email = "contact@mitchellneedham.com" } ]
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dynamic = [ "version" ]
+dependencies = [  ]
+keywords = [ "comments", "formatter", "linter", "pre-commit", "section-headers" ]
+
+urls.Homepage = "https://github.com/MitchellNeedham/sectionise"
+urls.Repository = "https://github.com/MitchellNeedham/sectionise"
+
+scripts.sectionise = "sectionise.cli:main"
+
+[dependency-groups]
+dev = [
+  "pre-commit>=4.5",
+  "pytest>=8",
+  "ruff>=0.14",
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.ruff]
+lint.select = [ "E", "F", "I", "W" ]
+lint.extend-select = [ "D" ]
+lint.ignore = [ "D105", "D107", "D413", "E501" ]
+lint.per-file-ignores."**/*.py" = [ "E731", "F403", "F405" ]
+lint.per-file-ignores."**/{__init__,conftest}.py" = [ "F401", "F403" ]
+lint.per-file-ignores."**/__init__.py" = [ "D" ]
+lint.per-file-ignores."tests/**/*.py" = [ "D" ]
+lint.pydocstyle.convention = "google"
+
+[tool.pytest.ini_options]
+testpaths = [ "tests" ]
+
+# Dogfood: sectionise standardises its own section headers with these settings.
+[tool.sectionise]
+width = 88
+style = "single"
+fill = "-"

sectionise-0.1.1/sectionise/cli.py

@@ -0,0 +1,150 @@
+"""Command-line entry point for sectionise.
+
+Resolves settings with the precedence flags > `[tool.sectionise]` in the nearest
+`pyproject.toml` > built-in defaults, then lints or autofixes the given files.
+Exits non-zero when it changed anything or hit an over-long title, matching the
+pre-commit formatter convention.
+"""
+
+import argparse
+import tomllib
+from pathlib import Path
+
+from . import core
+
+
+def _find_pyproject(start: Path) -> Path | None:
+    """Return the nearest `pyproject.toml` at or above `start`, else `None`."""
+    start = start.resolve()
+    for parent in (start, *start.parents):
+        candidate = parent / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _load_config(path: Path | None) -> dict:
+    """Read the `[tool.sectionise]` table from a `pyproject.toml`.
+
+    Args:
+        path: The file to read, or `None`.
+
+    Returns:
+        The table as a dict, or an empty dict when absent or unreadable.
+    """
+    if path is None or not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+    tool = data.get("tool", {})
+    section = tool.get("sectionise", {})
+    return section if isinstance(section, dict) else {}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser.
+
+    Overridable options default to `None` so an unset flag falls through to
+    `pyproject.toml` and then the built-in default.
+    """
+    parser = argparse.ArgumentParser(
+        prog="sectionise",
+        description="Standardise section-header comment banners.",
+    )
+    parser.add_argument("filenames", nargs="*", help="Files to process.")
+    parser.add_argument("--config", type=Path, default=None, help="pyproject.toml to read.")
+    parser.add_argument("--width", type=int, default=None, help="Target line length.")
+    parser.add_argument("--fill", default=None, help="Output fill character.")
+    parser.add_argument(
+        "--detect-chars", default=None, help="Characters recognised as banner fill."
+    )
+    parser.add_argument("--min-run", type=int, default=None, help="Minimum fill-run length.")
+    parser.add_argument(
+        "--style", choices=("single", "box"), default=None, help="Output form."
+    )
+    parser.add_argument(
+        "--max-title", type=int, default=None, help="Hard cap on title length."
+    )
+    parser.add_argument(
+        "--require-both-sides",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Only treat comments with fill on both sides as banners.",
+    )
+    parser.add_argument(
+        "--dividers",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Also standardise stand-alone title-less rules.",
+    )
+    parser.add_argument(
+        "--check", action="store_true", help="Report only; do not rewrite files."
+    )
+    return parser
+
+
+def _resolve_style(args: argparse.Namespace, config: dict) -> core.Style:
+    """Merge flags over `pyproject.toml` over defaults into a `Style`."""
+
+    def pick(flag_value, key, default):
+        if flag_value is not None:
+            return flag_value
+        return config.get(key, default)
+
+    return core.Style(
+        width=pick(args.width, "width", core.DEFAULT_WIDTH),
+        fill=pick(args.fill, "fill", core.DEFAULT_FILL),
+        detect_chars=pick(args.detect_chars, "detect_chars", core.DEFAULT_DETECT_CHARS),
+        min_run=pick(args.min_run, "min_run", core.DEFAULT_MIN_RUN),
+        require_both_sides=pick(args.require_both_sides, "require_both_sides", False),
+        dividers=pick(args.dividers, "dividers", False),
+        style=pick(args.style, "style", core.DEFAULT_STYLE),
+        max_title=pick(args.max_title, "max_title", None),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Lint or autofix section-header banners in the given files.
+
+    Args:
+        argv: Argument list; defaults to `sys.argv[1:]`.
+
+    Returns:
+        `1` if any file was (or would be) changed or a title was too long, else
+        `0`.
+    """
+    args = _build_parser().parse_args(argv)
+    config = _load_config(args.config or _find_pyproject(Path.cwd()))
+    style = _resolve_style(args, config)
+
+    changed_files: list[str] = []
+    all_errors: list[str] = []
+    for name in args.filenames:
+        path = Path(name)
+        syntax = core.syntax_for(path.suffix)
+        if syntax is None:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        new_text, changed, errors = core.process_text(text, syntax, style, name)
+        all_errors.extend(errors)
+        if changed:
+            changed_files.append(name)
+            if not args.check:
+                path.write_text(new_text, encoding="utf-8")
+
+    verb = "would reformat" if args.check else "reformatted"
+    for name in changed_files:
+        print(f"{verb} section headers in {name}")
+    for error in all_errors:
+        print(error)
+    return 1 if changed_files or all_errors else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())