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.
- py_sparcli-0.3.0.dist-info/METADATA +257 -0
- py_sparcli-0.3.0.dist-info/RECORD +61 -0
- py_sparcli-0.3.0.dist-info/WHEEL +4 -0
- py_sparcli-0.3.0.dist-info/licenses/LICENSE +21 -0
- sparcli/__init__.py +184 -0
- sparcli/core/__init__.py +92 -0
- sparcli/core/border.py +160 -0
- sparcli/core/color.py +306 -0
- sparcli/core/cursor.py +59 -0
- sparcli/core/geometry.py +141 -0
- sparcli/core/markup.py +215 -0
- sparcli/core/render.py +245 -0
- sparcli/core/style.py +128 -0
- sparcli/core/terminal.py +127 -0
- sparcli/core/text.py +143 -0
- sparcli/core/theme.py +117 -0
- sparcli/core/width.py +244 -0
- sparcli/errors.py +38 -0
- sparcli/input/__init__.py +42 -0
- sparcli/input/calc.py +214 -0
- sparcli/input/confirm.py +188 -0
- sparcli/input/datepicker.py +298 -0
- sparcli/input/editor.py +189 -0
- sparcli/input/event.py +551 -0
- sparcli/input/field.py +90 -0
- sparcli/input/fuzzy.py +401 -0
- sparcli/input/guard.py +103 -0
- sparcli/input/history.py +160 -0
- sparcli/input/line_edit.py +229 -0
- sparcli/input/number.py +232 -0
- sparcli/input/outcome.py +107 -0
- sparcli/input/password.py +233 -0
- sparcli/input/prompt.py +134 -0
- sparcli/input/select.py +336 -0
- sparcli/input/shortcut.py +123 -0
- sparcli/input/text.py +564 -0
- sparcli/input/textarea.py +242 -0
- sparcli/input/validate.py +67 -0
- sparcli/output/__init__.py +56 -0
- sparcli/output/alert.py +107 -0
- sparcli/output/badge.py +82 -0
- sparcli/output/box.py +196 -0
- sparcli/output/columns.py +157 -0
- sparcli/output/compose.py +111 -0
- sparcli/output/diff.py +229 -0
- sparcli/output/kv.py +175 -0
- sparcli/output/layout.py +77 -0
- sparcli/output/list.py +274 -0
- sparcli/output/live.py +129 -0
- sparcli/output/multiprogress.py +73 -0
- sparcli/output/pager.py +83 -0
- sparcli/output/panel.py +125 -0
- sparcli/output/progress.py +233 -0
- sparcli/output/rule.py +134 -0
- sparcli/output/spinner.py +138 -0
- sparcli/output/table/__init__.py +17 -0
- sparcli/output/table/plan.py +198 -0
- sparcli/output/table/render.py +302 -0
- sparcli/output/table/table.py +351 -0
- sparcli/output/tree.py +157 -0
- 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)
|
sparcli/output/pager.py
ADDED
|
@@ -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
|
sparcli/output/panel.py
ADDED
|
@@ -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)
|