py-sparcli 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. py_sparcli-0.3.0.dist-info/METADATA +257 -0
  2. py_sparcli-0.3.0.dist-info/RECORD +61 -0
  3. py_sparcli-0.3.0.dist-info/WHEEL +4 -0
  4. py_sparcli-0.3.0.dist-info/licenses/LICENSE +21 -0
  5. sparcli/__init__.py +184 -0
  6. sparcli/core/__init__.py +92 -0
  7. sparcli/core/border.py +160 -0
  8. sparcli/core/color.py +306 -0
  9. sparcli/core/cursor.py +59 -0
  10. sparcli/core/geometry.py +141 -0
  11. sparcli/core/markup.py +215 -0
  12. sparcli/core/render.py +245 -0
  13. sparcli/core/style.py +128 -0
  14. sparcli/core/terminal.py +127 -0
  15. sparcli/core/text.py +143 -0
  16. sparcli/core/theme.py +117 -0
  17. sparcli/core/width.py +244 -0
  18. sparcli/errors.py +38 -0
  19. sparcli/input/__init__.py +42 -0
  20. sparcli/input/calc.py +214 -0
  21. sparcli/input/confirm.py +188 -0
  22. sparcli/input/datepicker.py +298 -0
  23. sparcli/input/editor.py +189 -0
  24. sparcli/input/event.py +551 -0
  25. sparcli/input/field.py +90 -0
  26. sparcli/input/fuzzy.py +401 -0
  27. sparcli/input/guard.py +103 -0
  28. sparcli/input/history.py +160 -0
  29. sparcli/input/line_edit.py +229 -0
  30. sparcli/input/number.py +232 -0
  31. sparcli/input/outcome.py +107 -0
  32. sparcli/input/password.py +233 -0
  33. sparcli/input/prompt.py +134 -0
  34. sparcli/input/select.py +336 -0
  35. sparcli/input/shortcut.py +123 -0
  36. sparcli/input/text.py +564 -0
  37. sparcli/input/textarea.py +242 -0
  38. sparcli/input/validate.py +67 -0
  39. sparcli/output/__init__.py +56 -0
  40. sparcli/output/alert.py +107 -0
  41. sparcli/output/badge.py +82 -0
  42. sparcli/output/box.py +196 -0
  43. sparcli/output/columns.py +157 -0
  44. sparcli/output/compose.py +111 -0
  45. sparcli/output/diff.py +229 -0
  46. sparcli/output/kv.py +175 -0
  47. sparcli/output/layout.py +77 -0
  48. sparcli/output/list.py +274 -0
  49. sparcli/output/live.py +129 -0
  50. sparcli/output/multiprogress.py +73 -0
  51. sparcli/output/pager.py +83 -0
  52. sparcli/output/panel.py +125 -0
  53. sparcli/output/progress.py +233 -0
  54. sparcli/output/rule.py +134 -0
  55. sparcli/output/spinner.py +138 -0
  56. sparcli/output/table/__init__.py +17 -0
  57. sparcli/output/table/plan.py +198 -0
  58. sparcli/output/table/render.py +302 -0
  59. sparcli/output/table/table.py +351 -0
  60. sparcli/output/tree.py +157 -0
  61. sparcli/py.typed +0 -0
@@ -0,0 +1,73 @@
1
+ """
2
+ sparcli.output.multiprogress
3
+ =============================
4
+
5
+ Defines :class:`MultiProgress`, several progress bars updated together.
6
+
7
+ A :class:`MultiProgress` owns a list of :class:`~sparcli.output.progress.
8
+ ProgressBar` widgets, renders them as one block (one line per bar) and redraws
9
+ the whole group in place whenever a single bar is updated. A transient group
10
+ erases itself when the session ends instead of leaving the final bars behind.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from dataclasses import dataclass
16
+
17
+ from sparcli.core.render import Rendered
18
+ from sparcli.core.text import Line
19
+ from sparcli.output.live import InPlace
20
+ from sparcli.output.progress import ProgressBar
21
+
22
+
23
+ @dataclass(slots=True)
24
+ class _BarState:
25
+ """The live state of one bar within a :class:`MultiProgress`."""
26
+
27
+ bar: ProgressBar
28
+ value: float
29
+ total: float
30
+
31
+
32
+ class MultiProgress:
33
+ """A group of progress bars rendered as one block and updated in place."""
34
+
35
+ __slots__ = ("_bars", "_inplace", "_transient")
36
+
37
+ def __init__(self, *, inplace: InPlace | None = None) -> None:
38
+ self._bars: list[_BarState] = []
39
+ self._inplace = inplace or InPlace.create()
40
+ self._transient = False
41
+
42
+ def transient(self) -> MultiProgress:
43
+ """Erases all bars when the session ends and returns the group."""
44
+ self._transient = True
45
+ return self
46
+
47
+ def add(self, bar: ProgressBar) -> int:
48
+ """Adds a bar with default progress and returns its index."""
49
+ self._bars.append(_BarState(bar=bar, value=0.0, total=1.0))
50
+ return len(self._bars) - 1
51
+
52
+ def update(self, index: int, value: float, total: float) -> None:
53
+ """Updates the bar at ``index`` and redraws the whole group."""
54
+ if 0 <= index < len(self._bars):
55
+ state = self._bars[index]
56
+ state.value = value
57
+ state.total = total
58
+ self._inplace.draw(self.frame())
59
+
60
+ def finish(self) -> None:
61
+ """Ends the session, leaving or erasing the bars."""
62
+ if self._transient:
63
+ self._inplace.clear()
64
+ else:
65
+ self._inplace.finish()
66
+
67
+ def frame(self) -> Rendered:
68
+ """Builds the combined frame of all bars."""
69
+ lines: list[Line] = []
70
+ for state in self._bars:
71
+ rendered = state.bar.bar(state.value, state.total)
72
+ lines.extend(rendered.lines)
73
+ return Rendered(lines)
@@ -0,0 +1,83 @@
1
+ """
2
+ sparcli.output.pager
3
+ ====================
4
+
5
+ Pipes long output through ``$PAGER``, ``less`` or ``more``.
6
+
7
+ When output is not a terminal (and the pager is not forced), content is printed
8
+ directly instead of spawning a pager. Otherwise the widget renders at the
9
+ terminal width, spawns the resolved pager as an argument list (never through a
10
+ shell) and pipes the ANSI-encoded content into its standard input.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import io
16
+ import os
17
+ import subprocess
18
+
19
+ from sparcli.core.render import Renderable, write_rendered
20
+ from sparcli.core.terminal import ColorSupport, is_output_tty, term_width
21
+ from sparcli.errors import ConfigError
22
+
23
+ # The default pager command string for the current platform.
24
+ _DEFAULT_PAGER = "more" if os.name == "nt" else "less -R"
25
+
26
+
27
+ class Pager:
28
+ """Pages content through an external pager."""
29
+
30
+ __slots__ = ("_command", "_always")
31
+
32
+ def __init__(
33
+ self, *, command: str | None = None, always: bool = False
34
+ ) -> None:
35
+ self._command = command
36
+ self._always = always
37
+
38
+ def command(self, command: str) -> Pager:
39
+ """Overrides the pager command (whitespace-split, no shell)."""
40
+ self._command = command
41
+ return self
42
+
43
+ def always(self) -> Pager:
44
+ """Pages even when output is not a terminal and returns the pager."""
45
+ self._always = True
46
+ return self
47
+
48
+ def page(self, content: Renderable) -> None:
49
+ """
50
+ Pages ``content``, falling back to a direct print off-terminal.
51
+
52
+ Parameters
53
+ ----------
54
+ content : Renderable
55
+ The widget to page.
56
+
57
+ Raises
58
+ ------
59
+ ConfigError
60
+ If the resolved pager command is empty.
61
+ """
62
+ if not self._always and not is_output_tty():
63
+ content.print()
64
+ return
65
+ rendered = content.render(term_width())
66
+ argv = self.resolve_command().split()
67
+ if not argv:
68
+ raise ConfigError("empty pager")
69
+ buffer = io.StringIO()
70
+ write_rendered(buffer, rendered, ColorSupport.TRUECOLOR)
71
+ with subprocess.Popen( # noqa: S603
72
+ argv, stdin=subprocess.PIPE, text=True
73
+ ) as process:
74
+ process.communicate(buffer.getvalue())
75
+
76
+ def resolve_command(self) -> str:
77
+ """Resolves the pager command string."""
78
+ if self._command is not None:
79
+ return self._command
80
+ value = os.environ.get("PAGER")
81
+ if value is not None and value.strip():
82
+ return value
83
+ return _DEFAULT_PAGER
@@ -0,0 +1,125 @@
1
+ """
2
+ sparcli.output.panel
3
+ ===================
4
+
5
+ Defines :class:`Panel`, a bordered box framing rich content.
6
+
7
+ A panel wraps text or any rendered block in a border with optional title,
8
+ subtitle, padding and fill. It supports both a keyword constructor and fluent
9
+ builder methods, so ``Panel("hi", title="Note")`` and
10
+ ``Panel("hi").title("Note")`` are equivalent.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from sparcli.core.border import BorderType
16
+ from sparcli.core.geometry import Align, Edges, Position, Title
17
+ from sparcli.core.render import Renderable, Rendered
18
+ from sparcli.core.style import Style
19
+ from sparcli.core.text import IntoText, Text, into_text
20
+ from sparcli.core.theme import theme
21
+ from sparcli.output.box import BoxOpts, draw_box
22
+
23
+ IntoTitle = IntoText | Title
24
+
25
+
26
+ def into_title(value: IntoTitle) -> Title:
27
+ """Coerces a string, rich text or title into a :class:`Title`."""
28
+ if isinstance(value, Title):
29
+ return value
30
+ return Title.new(value)
31
+
32
+
33
+ class Panel(Renderable):
34
+ """A bordered box framing rich content."""
35
+
36
+ __slots__ = ("_content", "_opts")
37
+
38
+ def __init__(
39
+ self,
40
+ content: IntoText = "",
41
+ *,
42
+ border: BorderType | None = None,
43
+ border_style: Style | None = None,
44
+ fill: Style | None = None,
45
+ padding: Edges | None = None,
46
+ title: IntoTitle | None = None,
47
+ subtitle: IntoTitle | None = None,
48
+ width: int | None = None,
49
+ content_align: Align = Align.LEFT,
50
+ ) -> None:
51
+ self._content = _content_to_rendered(content)
52
+ self._opts = BoxOpts(
53
+ border=border if border is not None else theme().border,
54
+ border_style=border_style or Style.new(),
55
+ fill=fill or Style.new(),
56
+ padding=padding if padding is not None else Edges.symmetric(0, 1),
57
+ title=into_title(title) if title is not None else None,
58
+ subtitle=_as_subtitle(subtitle),
59
+ width=width,
60
+ content_align=content_align,
61
+ )
62
+
63
+ @classmethod
64
+ def from_rendered(cls, rendered: Rendered) -> Panel:
65
+ """Returns a panel framing an already rendered block."""
66
+ panel = cls()
67
+ panel._content = rendered
68
+ return panel
69
+
70
+ def border(self, border: BorderType) -> Panel:
71
+ """Sets the border type and returns the panel."""
72
+ self._opts.border = border
73
+ return self
74
+
75
+ def border_style(self, style: Style) -> Panel:
76
+ """Sets the border style and returns the panel."""
77
+ self._opts.border_style = style
78
+ return self
79
+
80
+ def fill(self, style: Style) -> Panel:
81
+ """Sets the interior fill style and returns the panel."""
82
+ self._opts.fill = style
83
+ return self
84
+
85
+ def padding(self, edges: Edges) -> Panel:
86
+ """Sets the interior padding and returns the panel."""
87
+ self._opts.padding = edges
88
+ return self
89
+
90
+ def title(self, title: IntoTitle) -> Panel:
91
+ """Sets the title and returns the panel."""
92
+ self._opts.title = into_title(title)
93
+ return self
94
+
95
+ def subtitle(self, subtitle: IntoTitle) -> Panel:
96
+ """Sets the bottom subtitle and returns the panel."""
97
+ self._opts.subtitle = _as_subtitle(subtitle)
98
+ return self
99
+
100
+ def width(self, width: int) -> Panel:
101
+ """Fixes the outer width and returns the panel."""
102
+ self._opts.width = width
103
+ return self
104
+
105
+ def content_align(self, align: Align) -> Panel:
106
+ """Sets the content alignment and returns the panel."""
107
+ self._opts.content_align = align
108
+ return self
109
+
110
+ def render(self, max_width: int) -> Rendered:
111
+ """Renders the framed panel into at most ``max_width`` columns."""
112
+ return draw_box(self._content, self._opts, max_width)
113
+
114
+
115
+ def _content_to_rendered(content: IntoText) -> Rendered:
116
+ """Converts widget content into a rendered block."""
117
+ text: Text = into_text(content)
118
+ return Rendered.from_text(text)
119
+
120
+
121
+ def _as_subtitle(value: IntoTitle | None) -> Title | None:
122
+ """Coerces a subtitle value, forcing it to sit on the bottom edge."""
123
+ if value is None:
124
+ return None
125
+ return into_title(value).with_position(Position.BOTTOM)
@@ -0,0 +1,233 @@
1
+ """
2
+ sparcli.output.progress
3
+ ========================
4
+
5
+ Defines progress bars with multiple styles and threshold-based coloring.
6
+
7
+ A :class:`ProgressBar` renders a fixed-width bar of filled and empty cells with
8
+ an optional label, caps, percentage and value suffix. The static
9
+ :meth:`ProgressBar.bar` builds the line without touching the terminal, while
10
+ :meth:`ProgressBar.draw` redraws it in place via
11
+ :class:`~sparcli.output.live.InPlace`. A :class:`Thresholds` value switches the
12
+ fill color as the completion ratio crosses configured cut-off points.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import enum
18
+ import math
19
+ from dataclasses import dataclass
20
+
21
+ from sparcli.core.color import Color
22
+ from sparcli.core.render import Rendered
23
+ from sparcli.core.style import Style
24
+ from sparcli.core.text import Line, Span
25
+ from sparcli.core.theme import theme
26
+ from sparcli.output.live import InPlace
27
+
28
+ # Default bar width in columns.
29
+ DEFAULT_WIDTH = 30
30
+
31
+
32
+ class ProgressStyle(enum.Enum):
33
+ """The visual style of the filled and empty bar cells."""
34
+
35
+ BLOCK = enum.auto()
36
+ ASCII = enum.auto()
37
+ LINE = enum.auto()
38
+ SHADED = enum.auto()
39
+
40
+
41
+ # The (filled, empty) glyph pair for each progress style.
42
+ _PROGRESS_GLYPHS: dict[ProgressStyle, tuple[str, str]] = {
43
+ ProgressStyle.BLOCK: ("█", "░"),
44
+ ProgressStyle.ASCII: ("#", "-"),
45
+ ProgressStyle.LINE: ("━", "╌"),
46
+ ProgressStyle.SHADED: ("▓", "░"),
47
+ }
48
+
49
+
50
+ @dataclass(frozen=True, slots=True)
51
+ class Thresholds:
52
+ """
53
+ Threshold-based fill colors keyed on the completion ratio.
54
+
55
+ Attributes
56
+ ----------
57
+ mid : float
58
+ Ratio at or above which the mid color applies.
59
+ high : float
60
+ Ratio at or above which the high color applies.
61
+ low_color : Color
62
+ Color used below ``mid``.
63
+ mid_color : Color
64
+ Color used in the ``[mid, high)`` range.
65
+ high_color : Color
66
+ Color used at or above ``high``.
67
+ """
68
+
69
+ mid: float
70
+ high: float
71
+ low_color: Color
72
+ mid_color: Color
73
+ high_color: Color
74
+
75
+
76
+ class ProgressBar:
77
+ """A configurable, single-line progress bar."""
78
+
79
+ __slots__ = (
80
+ "_style",
81
+ "_left_cap",
82
+ "_right_cap",
83
+ "_fill_color",
84
+ "_empty_color",
85
+ "_thresholds",
86
+ "_show_percent",
87
+ "_show_value",
88
+ "_width",
89
+ "_label",
90
+ "_label_style",
91
+ "_inplace",
92
+ )
93
+
94
+ def __init__(self, *, inplace: InPlace | None = None) -> None:
95
+ active = theme()
96
+ self._style = ProgressStyle.BLOCK
97
+ self._left_cap = ""
98
+ self._right_cap = ""
99
+ self._fill_color = active.accent
100
+ self._empty_color = Color.DARK_GRAY
101
+ self._thresholds: Thresholds | None = None
102
+ self._show_percent = True
103
+ self._show_value = False
104
+ self._width = DEFAULT_WIDTH
105
+ self._label = ""
106
+ self._label_style = active.secondary
107
+ self._inplace = inplace
108
+
109
+ def style(self, style: ProgressStyle) -> ProgressBar:
110
+ """Sets the bar style and returns the bar."""
111
+ self._style = style
112
+ return self
113
+
114
+ def caps(self, left: str, right: str) -> ProgressBar:
115
+ """Sets the left and right cap strings and returns the bar."""
116
+ self._left_cap = left
117
+ self._right_cap = right
118
+ return self
119
+
120
+ def fill_color(self, color: Color) -> ProgressBar:
121
+ """Sets the fill color and returns the bar."""
122
+ self._fill_color = color
123
+ return self
124
+
125
+ def thresholds(self, thresholds: Thresholds) -> ProgressBar:
126
+ """Sets threshold-based fill colors and returns the bar."""
127
+ self._thresholds = thresholds
128
+ return self
129
+
130
+ def show_percent(self, show: bool) -> ProgressBar:
131
+ """Toggles the percentage suffix and returns the bar."""
132
+ self._show_percent = show
133
+ return self
134
+
135
+ def show_value(self, show: bool) -> ProgressBar:
136
+ """Toggles the ``(value/total)`` suffix and returns the bar."""
137
+ self._show_value = show
138
+ return self
139
+
140
+ def width(self, width: int) -> ProgressBar:
141
+ """Sets the bar width in columns (at least one) and returns the bar."""
142
+ self._width = max(width, 1)
143
+ return self
144
+
145
+ def label(self, label: str) -> ProgressBar:
146
+ """Sets a leading label and returns the bar."""
147
+ self._label = label
148
+ return self
149
+
150
+ def bar(self, value: float, total: float) -> Rendered:
151
+ """Builds the bar as a single rendered line for the given progress."""
152
+ ratio = _ratio_of(value, total)
153
+ filled = min(_round_half_up(ratio * self._width), self._width)
154
+ empty = self._width - filled
155
+ fill_glyph, empty_glyph = _PROGRESS_GLYPHS[self._style]
156
+ spans: list[Span] = []
157
+ self._push_label(spans)
158
+ self._push_cap(spans, self._left_cap)
159
+ spans.append(
160
+ Span.styled(
161
+ fill_glyph * filled,
162
+ Style.new().with_fg(self._resolve_fill_color(ratio)),
163
+ )
164
+ )
165
+ spans.append(
166
+ Span.styled(
167
+ empty_glyph * empty, Style.new().with_fg(self._empty_color)
168
+ )
169
+ )
170
+ self._push_cap(spans, self._right_cap)
171
+ self._push_suffix(spans, ratio, value, total)
172
+ return Rendered([Line(spans)])
173
+
174
+ def draw(self, value: float, total: float) -> None:
175
+ """Draws the bar in place (animated when on a terminal)."""
176
+ self._ensure_inplace().draw(self.bar(value, total))
177
+
178
+ def finish(self, value: float, total: float) -> None:
179
+ """Draws the final bar and ends the in-place session."""
180
+ inplace = self._ensure_inplace()
181
+ inplace.draw(self.bar(value, total))
182
+ inplace.finish()
183
+
184
+ def _resolve_fill_color(self, ratio: float) -> Color:
185
+ """Resolves the fill color for ``ratio``, honoring thresholds."""
186
+ bounds = self._thresholds
187
+ if bounds is None:
188
+ return self._fill_color
189
+ if ratio >= bounds.high:
190
+ return bounds.high_color
191
+ if ratio >= bounds.mid:
192
+ return bounds.mid_color
193
+ return bounds.low_color
194
+
195
+ def _push_label(self, spans: list[Span]) -> None:
196
+ """Pushes the leading label span, if any."""
197
+ if self._label:
198
+ spans.append(Span.styled(f"{self._label} ", self._label_style))
199
+
200
+ def _push_cap(self, spans: list[Span], cap: str) -> None:
201
+ """Pushes a cap span, if non-empty."""
202
+ if cap:
203
+ spans.append(Span.raw(cap))
204
+
205
+ def _push_suffix(
206
+ self, spans: list[Span], ratio: float, value: float, total: float
207
+ ) -> None:
208
+ """Pushes the percentage and/or value suffix."""
209
+ if self._show_percent:
210
+ percent = _round_half_up(ratio * 100.0)
211
+ spans.append(Span.styled(f" {percent:>3}%", self._label_style))
212
+ if self._show_value:
213
+ spans.append(
214
+ Span.styled(f" ({value:.0f}/{total:.0f})", self._label_style)
215
+ )
216
+
217
+ def _ensure_inplace(self) -> InPlace:
218
+ """Returns the in-place engine, creating a lazy one on first use."""
219
+ if self._inplace is None:
220
+ self._inplace = InPlace.create()
221
+ return self._inplace
222
+
223
+
224
+ def _ratio_of(value: float, total: float) -> float:
225
+ """Clamps ``value / total`` into ``[0, 1]``; non-positive total is zero."""
226
+ if total <= 0.0:
227
+ return 0.0
228
+ return max(0.0, min(1.0, value / total))
229
+
230
+
231
+ def _round_half_up(value: float) -> int:
232
+ """Rounds a non-negative float half away from zero, matching Rust."""
233
+ return math.floor(value + 0.5)
sparcli/output/rule.py ADDED
@@ -0,0 +1,134 @@
1
+ """
2
+ sparcli.output.rule
3
+ ===================
4
+
5
+ Defines :class:`Rule`, a horizontal divider with an optional embedded title.
6
+
7
+ A rule fills its width with the border's horizontal glyph, painted in the
8
+ secondary style. When given a title, the label is embedded in the line with a
9
+ one-space pad on each side; a left- or right-aligned title keeps a single
10
+ connecting glyph on the outer edge, and a title too wide for the line replaces
11
+ it entirely. Both a keyword constructor and fluent builders are provided.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from sparcli.core.border import BorderType
17
+ from sparcli.core.geometry import Align, Edges
18
+ from sparcli.core.render import Renderable, Rendered
19
+ from sparcli.core.style import Style
20
+ from sparcli.core.text import IntoText, Line, Span, Text, into_text
21
+ from sparcli.core.theme import theme
22
+ from sparcli.output.compose import pad
23
+
24
+ _DEFAULT_PAD = 1
25
+ _CONNECTOR = 1
26
+
27
+
28
+ class Rule(Renderable):
29
+ """A horizontal divider line, optionally labelled with a title."""
30
+
31
+ __slots__ = (
32
+ "_title",
33
+ "_border",
34
+ "_style",
35
+ "_align",
36
+ "_width",
37
+ "_margin",
38
+ "_pad",
39
+ )
40
+
41
+ def __init__(
42
+ self,
43
+ title: IntoText | None = None,
44
+ *,
45
+ border: BorderType | None = None,
46
+ style: Style | None = None,
47
+ align: Align = Align.CENTER,
48
+ width: int | None = None,
49
+ margin: Edges | None = None,
50
+ ) -> None:
51
+ active = theme()
52
+ self._title = into_text(title) if title is not None else None
53
+ self._border = border if border is not None else active.border
54
+ self._style = style if style is not None else active.secondary
55
+ self._align = align
56
+ self._width = width
57
+ self._margin = margin if margin is not None else Edges()
58
+ self._pad = _DEFAULT_PAD
59
+
60
+ @classmethod
61
+ def with_title(cls, title: IntoText) -> Rule:
62
+ """Returns a rule with an embedded title."""
63
+ return cls(title)
64
+
65
+ def border(self, border: BorderType) -> Rule:
66
+ """Sets the line glyph style and returns the rule."""
67
+ self._border = border
68
+ return self
69
+
70
+ def style(self, style: Style) -> Rule:
71
+ """Sets the line glyph paint style and returns the rule."""
72
+ self._style = style
73
+ return self
74
+
75
+ def align(self, align: Align) -> Rule:
76
+ """Sets the title alignment and returns the rule."""
77
+ self._align = align
78
+ return self
79
+
80
+ def width(self, width: int) -> Rule:
81
+ """Sets a fixed width in columns and returns the rule."""
82
+ self._width = width
83
+ return self
84
+
85
+ def margin(self, margin: Edges) -> Rule:
86
+ """Sets the outer margin and returns the rule."""
87
+ self._margin = margin
88
+ return self
89
+
90
+ def render(self, max_width: int) -> Rendered:
91
+ """Renders the rule into at most ``max_width`` columns."""
92
+ total = self._width if self._width is not None else max_width
93
+ inner = max(0, total - self._margin.horizontal())
94
+ glyph = self._border.chars().horizontal
95
+ if self._title is None:
96
+ line = _fill_line(glyph, inner, self._style)
97
+ else:
98
+ line = self._titled_line(self._title, glyph, inner)
99
+ return pad(Rendered([line]), self._margin)
100
+
101
+ def _titled_line(self, title: Text, glyph: str, width: int) -> Line:
102
+ """Builds a rule line with an aligned, embedded title."""
103
+ title_line = title.lines[0] if title.lines else Line()
104
+ title_w = title_line.width() + 2 * self._pad
105
+ if title_w >= width:
106
+ return title_line
107
+ remaining = width - title_w
108
+ left, right = _split_runs(self._align, remaining)
109
+ pad_span = Span.raw(" " * self._pad)
110
+ spans = [_glyph_span(glyph, left, self._style), pad_span]
111
+ spans.extend(title_line.spans)
112
+ spans.append(pad_span)
113
+ spans.append(_glyph_span(glyph, right, self._style))
114
+ return Line(spans)
115
+
116
+
117
+ def _split_runs(align: Align, remaining: int) -> tuple[int, int]:
118
+ """Splits the leftover glyph run around the title per its alignment."""
119
+ if align is Align.LEFT:
120
+ return (min(_CONNECTOR, remaining), max(0, remaining - _CONNECTOR))
121
+ if align is Align.RIGHT:
122
+ return (max(0, remaining - _CONNECTOR), min(_CONNECTOR, remaining))
123
+ left = remaining // 2
124
+ return (left, remaining - left)
125
+
126
+
127
+ def _fill_line(glyph: str, width: int, style: Style) -> Line:
128
+ """Builds a line of ``width`` repeated glyphs."""
129
+ return Line([_glyph_span(glyph, width, style)])
130
+
131
+
132
+ def _glyph_span(glyph: str, count: int, style: Style) -> Span:
133
+ """Builds a span of ``count`` repeated glyphs."""
134
+ return Span.styled(glyph * max(0, count), style)