sectionise 0.2.0__tar.gz → 0.3.0__tar.gz

{sectionise-0.2.0 → sectionise-0.3.0}/.pre-commit-config.yaml

@@ -34,4 +34,8 @@ repos:
             entry: sectionise
             language: system
             types: [text]
+            # Markdown docs carry illustrative banners inside code fences that
+            # must not be reformatted; the tool cannot tell a fence from a real
+            # comment.
+            exclude: \.md$
             stages: [pre-commit]

{sectionise-0.2.0 → sectionise-0.3.0}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-07-23
+
+### Added
+
+- `fill_mode` (`width` or `fixed`) and `fill_count`, so single-line banners can
+  carry a set number of fill characters per run (`# ----- Title -----`) instead
+  of always padding to the target width. `align` still chooses the sides, and
+  box style and dividers are unaffected.
+- `bookend`, closing a single-line banner with a mirror of the comment opener
+  (`# --- Title --- #`, `// --- Title --- //`). A trailing opener is recognised
+  on input whether or not `bookend` is set.
+- Multi-character `fill` (for example `-=`), tiled and truncated to the target
+  width. Each of its characters is added to `detect_chars` so the output is
+  recognised on the next run.
+
+### Fixed
+
+- Fill characters joined to the title text (`_function_name`, `#Nice`, `name_`)
+  are no longer stripped. Only stand-alone, whitespace-separated fill runs are
+  treated as decoration.
+
 ## [0.2.0] - 2026-07-23
 
 ### Added

{sectionise-0.2.0 → sectionise-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sectionise
-Version: 0.2.0
+Version: 0.3.0
 Summary: Standardise section-header comment banners
 Project-URL: Homepage, https://github.com/MitchellNeedham/sectionise
 Project-URL: Repository, https://github.com/MitchellNeedham/sectionise
@@ -135,7 +135,7 @@ pip install sectionise
 
 ```yaml
 - repo: https://github.com/MitchellNeedham/sectionise
-  rev: 0.2.0
+  rev: 0.3.0
   hooks:
       - id: sectionise
 ```
@@ -174,6 +174,9 @@ overrides are honoured.
 style = "single"        # or "box"
 fill = "-"
 align = "centre"        # or "left"
+fill_mode = "width"     # or "fixed"
+fill_count = 3          # fill characters per run when fill_mode = "fixed"
+bookend = false         # close a single-line banner with a mirror of the opener
 detect_chars = "-=*_~#—–─═"
 min_run = 3
 require_both_sides = false
@@ -189,8 +192,11 @@ encoding = "utf-8"
 | --- | --- | --- | --- |
 | `width` | `--width` | per language | Target total line length. |
 | `style` | `--style` | `single` | Output form: `single` line or 3-line `box`. |
-| `fill` | `--fill` | `-` | Output fill character. |
+| `fill` | `--fill` | `-` | Output fill. One or more characters; a multi-character fill is tiled to the width. |
 | `align` | `--align` | `centre` | Single-line title placement: `centre` or `left`. |
+| `fill_mode` | `--fill-mode` | `width` | Single-line fill: `width` (pad to `width`) or `fixed` (a set count per run). |
+| `fill_count` | `--fill-count` | `3` | Fill characters per run when `fill_mode` is `fixed`. Must be at least `min_run`. |
+| `bookend` | `--bookend` | `false` | Close a single-line banner with a mirror of the comment opener. Line comments only. |
 | `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. |
@@ -230,7 +236,63 @@ align = "left"
 # Loading models -----------------------------------------------------------------------
 ```
 
-Any single non-space character is a valid fill, including an emoji:
+A fixed number of fill characters per run, so the line length follows the title
+instead of the target width:
+
+```toml
+[tool.sectionise]
+fill_mode = "fixed"
+fill_count = 5
+```
+
+```
+# ----- Loading models -----
+# ----- Setup -----
+```
+
+`align` still decides the sides: `centre` (the default) puts a matching run on
+both sides as above, while `left` keeps the trailing run only (`# Loading models
+-----`). Box style and stand-alone dividers ignore `fill_mode` and always span
+`width`.
+
+Book-ended headers close with a mirror of the comment opener, so the line ends
+the way it starts:
+
+```toml
+[tool.sectionise]
+fill_mode = "fixed"
+fill_count = 4
+bookend = true
+```
+
+```
+# ---- Loading models ---- #
+```
+
+The closing marker is always the opener, so it matches by construction: a `//`
+comment closes with `//`, a `#` comment with `#`. Block comments already close
+with their own token, so `bookend` leaves them alone. A trailing opener is
+recognised on input whether or not `bookend` is set, so existing
+`// --- x --- //` banners are picked up either way.
+
+The fill can be more than one character; a multi-character fill is tiled and
+truncated to reach the width:
+
+```toml
+[tool.sectionise]
+fill = "=-"
+fill_mode = "fixed"
+fill_count = 8
+```
+
+```
+# =-=-=-=- Loading models =-=-=-=-
+```
+
+A fill longer than the run it fills is truncated to its leading characters, so
+in `fixed` mode a fill longer than `fill_count` is cut mid-motif.
+
+Any non-space fill is valid, including an emoji:
 
 ```toml
 [tool.sectionise]
@@ -243,7 +305,7 @@ width = 40
 ```
 
 `width` counts characters, not display columns, so a double-width emoji fill
-lands on target by count but overshoots visually. Fun, not recommended.
+lands on target by count but is wider on screen.
 
 ### Per-language overrides
 

{sectionise-0.2.0 → sectionise-0.3.0}/README.md

@@ -118,7 +118,7 @@ pip install sectionise
 
 ```yaml
 - repo: https://github.com/MitchellNeedham/sectionise
-  rev: 0.2.0
+  rev: 0.3.0
   hooks:
       - id: sectionise
 ```
@@ -157,6 +157,9 @@ overrides are honoured.
 style = "single"        # or "box"
 fill = "-"
 align = "centre"        # or "left"
+fill_mode = "width"     # or "fixed"
+fill_count = 3          # fill characters per run when fill_mode = "fixed"
+bookend = false         # close a single-line banner with a mirror of the opener
 detect_chars = "-=*_~#—–─═"
 min_run = 3
 require_both_sides = false
@@ -172,8 +175,11 @@ encoding = "utf-8"
 | --- | --- | --- | --- |
 | `width` | `--width` | per language | Target total line length. |
 | `style` | `--style` | `single` | Output form: `single` line or 3-line `box`. |
-| `fill` | `--fill` | `-` | Output fill character. |
+| `fill` | `--fill` | `-` | Output fill. One or more characters; a multi-character fill is tiled to the width. |
 | `align` | `--align` | `centre` | Single-line title placement: `centre` or `left`. |
+| `fill_mode` | `--fill-mode` | `width` | Single-line fill: `width` (pad to `width`) or `fixed` (a set count per run). |
+| `fill_count` | `--fill-count` | `3` | Fill characters per run when `fill_mode` is `fixed`. Must be at least `min_run`. |
+| `bookend` | `--bookend` | `false` | Close a single-line banner with a mirror of the comment opener. Line comments only. |
 | `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. |
@@ -213,7 +219,63 @@ align = "left"
 # Loading models -----------------------------------------------------------------------
 ```
 
-Any single non-space character is a valid fill, including an emoji:
+A fixed number of fill characters per run, so the line length follows the title
+instead of the target width:
+
+```toml
+[tool.sectionise]
+fill_mode = "fixed"
+fill_count = 5
+```
+
+```
+# ----- Loading models -----
+# ----- Setup -----
+```
+
+`align` still decides the sides: `centre` (the default) puts a matching run on
+both sides as above, while `left` keeps the trailing run only (`# Loading models
+-----`). Box style and stand-alone dividers ignore `fill_mode` and always span
+`width`.
+
+Book-ended headers close with a mirror of the comment opener, so the line ends
+the way it starts:
+
+```toml
+[tool.sectionise]
+fill_mode = "fixed"
+fill_count = 4
+bookend = true
+```
+
+```
+# ---- Loading models ---- #
+```
+
+The closing marker is always the opener, so it matches by construction: a `//`
+comment closes with `//`, a `#` comment with `#`. Block comments already close
+with their own token, so `bookend` leaves them alone. A trailing opener is
+recognised on input whether or not `bookend` is set, so existing
+`// --- x --- //` banners are picked up either way.
+
+The fill can be more than one character; a multi-character fill is tiled and
+truncated to reach the width:
+
+```toml
+[tool.sectionise]
+fill = "=-"
+fill_mode = "fixed"
+fill_count = 8
+```
+
+```
+# =-=-=-=- Loading models =-=-=-=-
+```
+
+A fill longer than the run it fills is truncated to its leading characters, so
+in `fixed` mode a fill longer than `fill_count` is cut mid-motif.
+
+Any non-space fill is valid, including an emoji:
 
 ```toml
 [tool.sectionise]
@@ -226,7 +288,7 @@ width = 40
 ```
 
 `width` counts characters, not display columns, so a double-width emoji fill
-lands on target by count but overshoots visually. Fun, not recommended.
+lands on target by count but is wider on screen.
 
 ### Per-language overrides
 

{sectionise-0.2.0 → sectionise-0.3.0}/sectionise/cli.py

@@ -141,7 +141,9 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Name used to pick the comment syntax when reading stdin (default a .py name).",
     )
     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(
+        "--fill", default=None, help="Output fill, one or more characters."
+    )
     parser.add_argument(
         "--detect-chars", default=None, help="Characters recognised as banner fill."
     )
@@ -163,6 +165,24 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Single-line title placement (default centre).",
     )
+    parser.add_argument(
+        "--fill-mode",
+        choices=("width", "fixed"),
+        default=None,
+        help="Single-line fill: pad to width, or a fixed count per run.",
+    )
+    parser.add_argument(
+        "--fill-count",
+        type=int,
+        default=None,
+        help="Fill characters per run when fill-mode is fixed (default 3).",
+    )
+    parser.add_argument(
+        "--bookend",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Close a single-line banner with a mirror of the comment opener.",
+    )
     parser.add_argument(
         "--max-title", type=int, default=None, help="Hard cap on title length."
     )
@@ -231,6 +251,9 @@ def _resolve_style(
         boxes=pick(args.boxes, "boxes", True),
         style=pick(args.style, "style", core.DEFAULT_STYLE),
         align=pick(args.align, "align", core.DEFAULT_ALIGN),
+        fill_mode=pick(args.fill_mode, "fill_mode", core.DEFAULT_FILL_MODE),
+        fill_count=pick(args.fill_count, "fill_count", core.DEFAULT_FILL_COUNT),
+        bookend=pick(args.bookend, "bookend", False),
         tab_width=pick(args.tab_width, "tab_width", core.DEFAULT_TAB_WIDTH),
         max_title=pick(args.max_title, "max_title", None),
     )

{sectionise-0.2.0 → sectionise-0.3.0}/sectionise/core.py

@@ -31,6 +31,8 @@ DEFAULT_DETECT_CHARS = "-=*_~#—–─═"
 DEFAULT_MIN_RUN = 3
 DEFAULT_STYLE = "single"
 DEFAULT_ALIGN = "centre"
+DEFAULT_FILL_MODE = "width"
+DEFAULT_FILL_COUNT = 3
 DEFAULT_TAB_WIDTH = 8
 
 # Comment syntax as (opener, closer). The closer is empty for line comments and
@@ -129,7 +131,9 @@ class Style:
 
     Attributes:
         width: Target total line length for a rewritten banner or rule.
-        fill: The single fill character used in output.
+        fill: The fill used in output. Usually one character; a multi-character
+            fill is tiled and truncated to the exact width (`-=` gives
+            `-=-=-=-`), and each of its characters is added to `detect_chars`.
         detect_chars: Characters recognised as banner fill in input.
         min_run: Minimum identical-fill run length to count as a banner side.
         require_both_sides: Only treat a comment as a banner when it has a fill
@@ -141,6 +145,19 @@ class Style:
         align: Single-line title placement, `centre` (fill both sides) or `left`
             (title first, fill trailing). The American spelling `center` is
             accepted and normalised to `centre`.
+        fill_mode: How much fill a single-line banner carries, `width` (pad to
+            the target `width`) or `fixed` (`fill_count` characters per run, so
+            the line length grows with the title). `align` still decides the
+            sides: `centre` fills both, `left` fills only after the title. Box
+            style and stand-alone dividers are unaffected and always span
+            `width`.
+        fill_count: Fill characters per run when `fill_mode` is `fixed`. Must be
+            at least `min_run`, so a rendered banner is still recognised as one.
+        bookend: Close a single-line banner with a mirror of the comment opener,
+            so the line ends the way it starts (`# --- Title --- #`,
+            `// --- Title --- //`). Line comments only; block comments already
+            close with their own token, and box style is unaffected. A trailing
+            opener is always recognised on input regardless of this setting.
         tab_width: Columns a leading tab occupies, so tab-indented banners reach
             the target width.
         max_title: Optional hard cap on title length, on top of the width fit.
@@ -155,6 +172,9 @@ class Style:
     boxes: bool = True
     style: str = DEFAULT_STYLE
     align: str = DEFAULT_ALIGN
+    fill_mode: str = DEFAULT_FILL_MODE
+    fill_count: int = DEFAULT_FILL_COUNT
+    bookend: bool = False
     tab_width: int = DEFAULT_TAB_WIDTH
     max_title: int | None = None
 
@@ -180,9 +200,13 @@ class Style:
             raise ValueError(
                 f"min_run must be a positive integer, got {self.min_run!r}"
             )
-        if not isinstance(self.fill, str) or len(self.fill) != 1 or self.fill.isspace():
+        if (
+            not isinstance(self.fill, str)
+            or not self.fill
+            or any(char.isspace() for char in self.fill)
+        ):
             raise ValueError(
-                f"fill must be a single non-space character, got {self.fill!r}"
+                f"fill must be a non-empty string without whitespace, got {self.fill!r}"
             )
         if not isinstance(self.detect_chars, str) or not self.detect_chars:
             raise ValueError(
@@ -202,6 +226,25 @@ class Style:
             object.__setattr__(self, "align", "centre")
         if self.align not in ("centre", "left"):
             raise ValueError(f"align must be 'centre' or 'left', got {self.align!r}")
+        if self.fill_mode not in ("width", "fixed"):
+            raise ValueError(
+                f"fill_mode must be 'width' or 'fixed', got {self.fill_mode!r}"
+            )
+        if (
+            not isinstance(self.fill_count, int)
+            or isinstance(self.fill_count, bool)
+            or self.fill_count < 1
+        ):
+            raise ValueError(
+                f"fill_count must be a positive integer, got {self.fill_count!r}"
+            )
+        # A fixed run shorter than min_run would not be re-detected as a banner,
+        # so a freshly written header could not be re-fitted.
+        if self.fill_mode == "fixed" and self.fill_count < self.min_run:
+            raise ValueError(
+                f"fill_count must be at least min_run ({self.min_run}) in fixed "
+                f"mode, got {self.fill_count}"
+            )
         if self.max_title is not None and (
             not isinstance(self.max_title, int)
             or isinstance(self.max_title, bool)
@@ -210,10 +253,14 @@ class Style:
             raise ValueError(
                 f"max_title must be a positive integer or unset, got {self.max_title!r}"
             )
-        # The output fill must be recognised on the next run, else a freshly
-        # written banner would not be seen as one and could not be re-fitted.
-        if self.fill not in self.detect_chars:
-            object.__setattr__(self, "detect_chars", self.detect_chars + self.fill)
+        # Every output fill character must be recognised on the next run, else a
+        # freshly written banner would not be seen as one and could not be
+        # re-fitted. A multi-character fill seeds each of its characters.
+        missing = "".join(
+            dict.fromkeys(c for c in self.fill if c not in self.detect_chars)
+        )
+        if missing:
+            object.__setattr__(self, "detect_chars", self.detect_chars + missing)
 
 
 Syntax = tuple[str, str]
@@ -450,9 +497,41 @@ def _extract(content: str, syntax: tuple[str, str]) -> tuple[str, str] | None:
         if not inner.rstrip().endswith(closer):
             return None
         inner = inner.rstrip()[: -len(closer)]
+    else:
+        # A line-comment banner may be book-ended with a mirror of the opener
+        # (`# --- x --- #`, `// --- x --- //`). Drop a stand-alone trailing
+        # opener so the title is recovered, whatever the `bookend` setting is,
+        # since the opener may not be a detectable fill character.
+        trimmed = inner.rstrip()
+        if trimmed.endswith(opener) and (
+            len(trimmed) == len(opener) or trimmed[-len(opener) - 1].isspace()
+        ):
+            inner = trimmed[: -len(opener)]
     return indent, inner
 
 
+def _strip_edge_fill(text: str, detect_chars: str) -> str:
+    """Drop whitespace-separated fill runs from each edge of `text`.
+
+    A run of a fill character that stands alone, bounded by whitespace or the
+    string edge, is decoration and is removed, so `title --- #` reduces to
+    `title`. A fill character joined to the title text with no space, as in
+    `_function_name` or `#Nice`, is part of the title and kept.
+    """
+    s = text.strip()
+    while s and s[0] in detect_chars:
+        run = len(s) - len(s.lstrip(s[0]))
+        if run < len(s) and not s[run].isspace():
+            break  # attached to the title text, so keep it
+        s = s[run:].lstrip()
+    while s and s[-1] in detect_chars:
+        run = len(s) - len(s.rstrip(s[-1]))
+        if run < len(s) and not s[-1 - run].isspace():
+            break  # attached to the title text, so keep it
+        s = s[: len(s) - run].rstrip()
+    return s
+
+
 def _side_runs(inner: str, style: Style) -> tuple[int, int, str]:
     """Measure the leading and trailing fill runs and the title between them.
 
@@ -466,20 +545,16 @@ def _side_runs(inner: str, style: Style) -> tuple[int, int, str]:
     stripped = inner.strip()
     if not stripped:
         return 0, 0, ""
+    # A fill run is any maximal run of detect characters, not just one repeated
+    # character, so a multi-character fill motif (`-=-=-=`) reads as a single
+    # run and the tool's own output round-trips.
     lead = 0
-    if stripped[0] in style.detect_chars:
-        char = stripped[0]
-        while lead < len(stripped) and stripped[lead] == char:
-            lead += 1
+    while lead < len(stripped) and stripped[lead] in style.detect_chars:
+        lead += 1
     trail = 0
-    if stripped[-1] in style.detect_chars:
-        char = stripped[-1]
-        while trail < len(stripped) and stripped[-1 - trail] == char:
-            trail += 1
-    # Strip any residual fill characters left at the title edges, so decoration
-    # like a trailing lone `#` (`# --- title --- #`) cannot drag the real fill
-    # run into the title.
-    title = stripped[lead : len(stripped) - trail].strip(style.detect_chars + " \t")
+    while trail < len(stripped) and stripped[-1 - trail] in style.detect_chars:
+        trail += 1
+    title = _strip_edge_fill(stripped[lead : len(stripped) - trail], style.detect_chars)
     return lead, trail, title
 
 
@@ -574,23 +649,53 @@ def _match_box(
     return None
 
 
+def _close_part(syntax: tuple[str, str], style: Style) -> str:
+    """Return the trailing part of a single-line banner (space plus closer).
+
+    A block comment uses its own closer. A line comment has none, but closes
+    with a mirror of the opener when `bookend` is on, and is otherwise bare.
+    """
+    opener, closer = syntax
+    if closer:
+        return f" {closer}"
+    return f" {opener}" if style.bookend else ""
+
+
+def _tile(fill: str, count: int) -> str:
+    """Return exactly `count` characters of the fill, tiling and truncating.
+
+    For a single-character fill this is just repetition; a multi-character fill
+    is repeated and cut to length, so `-=` at width 7 gives `-=-=-=-`.
+    """
+    if count <= 0:
+        return ""
+    return (fill * (count // len(fill) + 1))[:count]
+
+
 def _format_banner(
     indent: str, syntax: tuple[str, str], title: str, style: Style
 ) -> str:
     """Render a canonical single-line banner, centred or left-aligned."""
-    opener, closer = syntax
-    open_part = f"{opener} "
-    close_part = f" {closer}" if closer else ""
+    open_part = f"{syntax[0]} "
+    close_part = _close_part(syntax, style)
+    if style.fill_mode == "fixed":
+        run = _tile(style.fill, style.fill_count)
+        if style.align == "left":
+            return f"{indent}{open_part}{title} {run}{close_part}"
+        return f"{indent}{open_part}{run} {title} {run}{close_part}"
     indent_cols = _indent_width(indent, style.tab_width)
     if style.align == "left":
         used = indent_cols + len(open_part) + len(title) + 1 + len(close_part)
         count = max(style.width - used, style.min_run)
-        return f"{indent}{open_part}{title} {style.fill * count}{close_part}"
+        return f"{indent}{open_part}{title} {_tile(style.fill, count)}{close_part}"
     fixed = indent_cols + len(open_part) + 1 + len(title) + 1 + len(close_part)
     total = max(style.width - fixed, 2 * style.min_run)
     left = total // 2
     right = total - left
-    return f"{indent}{open_part}{style.fill * left} {title} {style.fill * right}{close_part}"
+    return (
+        f"{indent}{open_part}{_tile(style.fill, left)} {title} "
+        f"{_tile(style.fill, right)}{close_part}"
+    )
 
 
 def _format_rule(indent: str, syntax: tuple[str, str], style: Style) -> str:
@@ -602,7 +707,7 @@ def _format_rule(indent: str, syntax: tuple[str, str], style: Style) -> str:
     count = max(
         style.width - indent_cols - len(open_part) - len(close_part), style.min_run
     )
-    return f"{indent}{open_part}{style.fill * count}{close_part}"
+    return f"{indent}{open_part}{_tile(style.fill, count)}{close_part}"
 
 
 def _format_title_line(indent: str, syntax: tuple[str, str], title: str) -> str:
@@ -622,21 +727,30 @@ def _render(
     return [_format_banner(indent, syntax, title, style)]
 
 
-def _title_limit(indent: str, syntax: tuple[str, str], style: Style) -> int:
-    """Return the maximum title length that fits the chosen style and cap."""
+def _title_limit(indent: str, syntax: tuple[str, str], style: Style) -> int | None:
+    """Return the maximum title length for the style and cap, or `None`.
+
+    `None` means the title has no length limit, which is the case for a
+    fixed-fill single-line banner: its fill runs are a constant length, so the
+    line grows with the title and `width` imposes no bound. Only an explicit
+    `max_title` caps it.
+    """
     opener, closer = syntax
     open_part = f"{opener} "
-    close_part = f" {closer}" if closer else ""
+    if style.style != "box" and style.fill_mode == "fixed":
+        return style.max_title
     indent_cols = _indent_width(indent, style.tab_width)
     if style.style == "box":
-        fit = style.width - indent_cols - len(open_part) - len(close_part)
+        # Box is unaffected by bookend, so only its own block closer counts.
+        box_close = f" {closer}" if closer else ""
+        fit = style.width - indent_cols - len(open_part) - len(box_close)
     elif style.align == "left":
         fit = (
             style.width
             - indent_cols
             - len(open_part)
             - 1  # the space between the title and its trailing fill
-            - len(close_part)
+            - len(_close_part(syntax, style))
             - style.min_run
         )
     else:
@@ -645,7 +759,7 @@ def _title_limit(indent: str, syntax: tuple[str, str], style: Style) -> int:
             - indent_cols
             - len(open_part)
             - 2  # the two spaces framing the title
-            - len(close_part)
+            - len(_close_part(syntax, style))
             - 2 * style.min_run
         )
     fit = max(fit, 1)
@@ -695,7 +809,7 @@ def _emit_unit(
     """
     original = "".join(lines[start : end + 1])
     limit = _title_limit(indent, syntax, style)
-    if len(title) > limit:
+    if limit is not None and len(title) > limit:
         return original, False, _too_long_error(path, start + 1, title, limit, style)
 
     rendered = _render(indent, syntax, title, style)

{sectionise-0.2.0 → sectionise-0.3.0}/tests/test_cli.py

@@ -17,7 +17,7 @@ def write(path, text, encoding="utf-8"):
     return path
 
 
-# ---------------------------- Per-language defaults --------------------------
+# ------------------------------- Per-language defaults --------------------------------
 @pytest.mark.parametrize(
     "suffix, comment, expected_width",
     [
@@ -33,7 +33,7 @@ def test_builtin_default_width_per_language(tmp_path, suffix, comment, expected_
     assert len(f.read_text(encoding="utf-8").splitlines()[0]) == expected_width
 
 
-# ------------------------------ Config precedence ----------------------------
+# --------------------------------- Config precedence ----------------------------------
 def test_global_and_per_language_override(tmp_path):
     write(
         tmp_path / "pyproject.toml",
@@ -55,7 +55,30 @@ def test_flag_overrides_everything(tmp_path):
     assert len(f.read_text().splitlines()[0]) == 50
 
 
-# --------------------------------- Exit codes --------------------------------
+# ------------------------------------- Fill mode --------------------------------------
+def test_fixed_fill_mode_via_flags(tmp_path):
+    f = write(tmp_path / "a.py", "# ------- Setup -------\n")
+    assert main(["--fill-mode", "fixed", "--fill-count", "5", str(f)]) == 1
+    assert f.read_text(encoding="utf-8") == "# ----- Setup -----\n"
+
+
+def test_fixed_fill_mode_from_config(tmp_path):
+    write(
+        tmp_path / "pyproject.toml",
+        '[tool.sectionise]\nfill_mode = "fixed"\nfill_count = 4\n',
+    )
+    f = write(tmp_path / "a.py", "# --- Setup ---\n")
+    main([str(tmp_path)])
+    assert f.read_text(encoding="utf-8") == "# ---- Setup ----\n"
+
+
+def test_bookend_mirrors_opener_via_flag(tmp_path):
+    f = write(tmp_path / "a.py", "# --- Setup ---\n")
+    assert main(["--bookend", "--fill-mode", "fixed", "--fill-count", "4", str(f)]) == 1
+    assert f.read_text(encoding="utf-8") == "# ---- Setup ---- #\n"
+
+
+# ------------------------------------- Exit codes -------------------------------------
 def test_exit_zero_when_clean(tmp_path, capsys):
     f = write(tmp_path / "a.py", "# --- x ---\ncode = 1\n")
     main([str(f)])  # normalise first
@@ -74,7 +97,7 @@ def test_exit_two_on_over_long_title(tmp_path, capsys):
     assert "section title" in err  # errors go to stderr
 
 
-# ------------------------------- Check and diff ------------------------------
+# ----------------------------------- Check and diff -----------------------------------
 def test_check_does_not_write(tmp_path):
     f = write(tmp_path / "a.py", "# --- x ---\n")
     main(["--check", str(f)])
@@ -90,7 +113,7 @@ def test_diff_prints_and_does_not_write(tmp_path, capsys):
     assert f.read_text() == "# --- x ---\n"  # unchanged on disk
 
 
-# ---------------------------------- Stdin ------------------------------------
+# --------------------------------------- Stdin ----------------------------------------
 def test_stdin_writes_to_stdout(monkeypatch, capsys):
     monkeypatch.setattr("sys.stdin", io.StringIO("# --- hi ---\n"))
     rc = main(["--width", "40", "-"])
@@ -105,7 +128,7 @@ def test_stdin_filename_picks_syntax(monkeypatch, capsys):
     assert capsys.readouterr().out.startswith("// ")
 
 
-# ------------------------------ Directory walk -------------------------------
+# ----------------------------------- Directory walk -----------------------------------
 def test_directory_walk_skips_vendored_dirs(tmp_path):
     write(tmp_path / "pkg" / "y.py", "# --- y ---\n")
     write(tmp_path / ".venv" / "x.py", "# --- x ---\n")
@@ -125,7 +148,7 @@ def test_unsupported_explicit_file_warns(tmp_path, capsys):
     assert "unsupported" in capsys.readouterr().err
 
 
-# ---------------------------- Custom and shebang -----------------------------
+# --------------------------------- Custom and shebang ---------------------------------
 def test_custom_language_from_config(tmp_path):
     write(
         tmp_path / "pyproject.toml",
@@ -152,7 +175,7 @@ def test_shebang_extensionless_script(tmp_path):
     assert len(f.read_text().splitlines()[1]) == 88  # python default width
 
 
-# --------------------------- Encoding and endings ----------------------------
+# -------------------------------- Encoding and endings --------------------------------
 def test_lf_stays_lf(tmp_path):
     f = tmp_path / "a.py"
     f.write_bytes(b"# --- x ---\ncode = 1\n")

{sectionise-0.2.0 → sectionise-0.3.0}/tests/test_core.py

@@ -20,7 +20,7 @@ C = core.syntax_for(".c")  # both // and /* */
 
 Case = namedtuple("Case", "name style syntax src want")
 
-# ------------------------------ Transform table ------------------------------
+# ---------------------------------- Transform table -----------------------------------
 CASES = [
     Case(
         "centre from both sides",
@@ -64,6 +64,90 @@ CASES = [
         "# --- Setup ---\n",
         "# Setup --------------------------------\n",
     ),
+    Case(
+        "fixed fill, centre, matching run both sides",
+        dict(fill_mode="fixed"),
+        HASH,
+        "# ------- Setup -------\n",
+        "# --- Setup ---\n",
+    ),
+    Case(
+        "fixed fill honours fill_count",
+        dict(fill_mode="fixed", fill_count=5),
+        HASH,
+        "# --- HEADER ---\n",
+        "# ----- HEADER -----\n",
+    ),
+    Case(
+        "fixed fill, left align, trailing run only",
+        dict(fill_mode="fixed", align="left"),
+        HASH,
+        "# ------- Setup -------\n",
+        "# Setup ---\n",
+    ),
+    Case(
+        "fixed fill has no width bound so a long title fits",
+        dict(fill_mode="fixed", width=20),
+        HASH,
+        "# ===== a very long section title indeed =====\n",
+        "# --- a very long section title indeed ---\n",
+    ),
+    Case(
+        "box ignores fill_mode and still spans the width",
+        dict(fill_mode="fixed", style="box", width=40),
+        HASH,
+        "# --- Setup ---\n",
+        "# --------------------------------------\n# Setup\n# --------------------------------------\n",
+    ),
+    Case(
+        "bookend closes with a mirror of the opener",
+        dict(width=40, bookend=True),
+        HASH,
+        "# ------- Setup -------\n",
+        "# -------------- Setup --------------- #\n",
+    ),
+    Case(
+        "bookend, fixed fill",
+        dict(fill_mode="fixed", fill_count=4, bookend=True),
+        HASH,
+        "# --- NICE ---\n",
+        "# ---- NICE ---- #\n",
+    ),
+    Case(
+        "bookend mirrors a slash opener with hash fill",
+        dict(fill_mode="fixed", fill_count=5, fill="#", bookend=True),
+        SLASH,
+        "// --- HEADER ---\n",
+        "// ##### HEADER ##### //\n",
+    ),
+    Case(
+        "bookend, left align",
+        dict(width=40, align="left", bookend=True),
+        HASH,
+        "# ------- Setup -------\n",
+        "# Setup ------------------------------ #\n",
+    ),
+    Case(
+        "trailing opener marker recognised even with bookend off",
+        dict(width=40),
+        SLASH,
+        "// ##### HEADER ##### //\n",
+        "// -------------- HEADER ---------------\n",
+    ),
+    Case(
+        "multi-character fill is tiled to the width",
+        dict(width=40, fill="=-"),
+        HASH,
+        "# ------- Setup -------\n",
+        "# =-=-=-=-=-=-=-= Setup =-=-=-=-=-=-=-=-\n",
+    ),
+    Case(
+        "multi-character fill, fixed count",
+        dict(fill_mode="fixed", fill_count=6, fill="=-"),
+        HASH,
+        "# --- Setup ---\n",
+        "# =-=-=- Setup =-=-=-\n",
+    ),
     Case(
         "box collapses to single",
         dict(width=40, style="single"),
@@ -106,6 +190,27 @@ CASES = [
         "# ---------------- model config ---------------- #\n",
         "# ---------------------- model config ----------------------\n",
     ),
+    Case(
+        "leading fill char attached to title is kept",
+        dict(width=40),
+        HASH,
+        "# ------- _function_name -------\n",
+        "# ----------- _function_name -----------\n",
+    ),
+    Case(
+        "hash prefix in title is kept",
+        dict(width=40),
+        HASH,
+        "# --- #Nice ---\n",
+        "# --------------- #Nice ----------------\n",
+    ),
+    Case(
+        "trailing fill char attached to title is kept",
+        dict(width=40),
+        HASH,
+        "# --- name_ ---\n",
+        "# --------------- name_ ----------------\n",
+    ),
     Case(
         "title-less divider left alone by default",
         dict(width=40),
@@ -228,7 +333,7 @@ def test_changed_flag_matches_whether_output_differs(case):
     assert bool(changed) == (case.want != case.src)
 
 
-# ------------------------------ Ignored inputs -------------------------------
+# ----------------------------------- Ignored inputs -----------------------------------
 @pytest.mark.parametrize(
     "src",
     [
@@ -245,7 +350,7 @@ def test_left_alone(src):
     assert errors == []
 
 
-# ---------------------------- String protection -----------------------------
+# --------------------------------- String protection ----------------------------------
 def test_banner_inside_python_string_is_left_untouched():
     text = 'x = """\n# ==== not a comment ====\nhello\n"""\n'
     protected = core.protected_lines(text, ".py")
@@ -282,7 +387,7 @@ def test_backtick_template_literal_protects_banner():
     assert changed == 0
 
 
-# ------------------------------- Box handling --------------------------------
+# ------------------------------------ Box handling ------------------------------------
 def test_boxes_disabled_leaves_box_untouched():
     text = "# ======\n# Setup\n# ======\n"
     out, changed, _ = core.process_text(text, HASH, Style(boxes=False, width=40))
@@ -320,7 +425,7 @@ def test_box_rule_never_shorter_than_min_run(min_run):
     assert out.splitlines()[0] == "# " + "-" * min_run
 
 
-# ---------------------------- Over-long titles -------------------------------
+# ---------------------------------- Over-long titles ----------------------------------
 def test_too_long_single_title_errors_and_leaves_unchanged():
     text = "# --- a very long section title indeed ---\n"
     out, changed, errors = core.process_text(text, HASH, Style(width=20))
@@ -335,7 +440,7 @@ def test_box_style_accommodates_longer_titles():
     assert errors == []
 
 
-# ------------------------------- Alignment -----------------------------------
+# ------------------------------------- Alignment --------------------------------------
 def test_left_align_is_idempotent():
     style = Style(width=40, align="left")
     once = core._format_banner("", HASH, "Section name", style)
@@ -356,18 +461,22 @@ def test_tab_indent_counts_as_configured_columns():
     assert len(line.expandtabs(8)) == 40
 
 
-# ------------------------------- Validation ----------------------------------
+# ------------------------------------- Validation -------------------------------------
 @pytest.mark.parametrize(
     "kwargs, message",
     [
         (dict(width=0), "width"),
         (dict(width=-5), "width"),
         (dict(min_run=0), "min_run"),
-        (dict(fill="--"), "fill"),
+        (dict(fill=""), "fill"),
         (dict(fill=" "), "fill"),
+        (dict(fill="- "), "fill"),
         (dict(detect_chars=""), "detect_chars"),
         (dict(style="banner"), "style"),
         (dict(align="middle"), "align"),
+        (dict(fill_mode="stretch"), "fill_mode"),
+        (dict(fill_count=0), "fill_count"),
+        (dict(fill_mode="fixed", fill_count=2, min_run=3), "min_run"),
         (dict(tab_width=0), "tab_width"),
         (dict(max_title=0), "max_title"),
     ],
@@ -385,7 +494,15 @@ def test_fill_added_to_detect_chars_for_idempotency():
     assert changed == 0
 
 
-# ---------------------------- Language registry ------------------------------
+def test_multi_character_fill_seeds_each_char_and_round_trips():
+    style = Style(fill="<>", detect_chars="-=")
+    assert "<" in style.detect_chars and ">" in style.detect_chars
+    once = core._format_banner("", HASH, "Title", style)
+    _, changed, _ = core.process_text(once + "\n", HASH, style)
+    assert changed == 0
+
+
+# --------------------------------- Language registry ----------------------------------
 @pytest.mark.parametrize(
     "suffix, language, width",
     [