logbar 0.2.4__tar.gz → 0.3.0__tar.gz

{logbar-0.2.4 → logbar-0.3.0}/LogBar.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LogBar
-Version: 0.2.4
+Version: 0.3.0
 Summary: A unified Logger and ProgressBar util with zero dependencies.
 Author-email: ModelCloud <qubitium@modelcloud.ai>
 License-Expression: Apache-2.0
@@ -36,6 +36,7 @@ Dynamic: license-file
 - Shared singleton logger with per-level colorized output.
 - `once` helpers prevent duplicate log spam automatically.
 - Stackable progress bars that stay anchored while your logs flow freely.
+- Sub-cell Unicode bar rasterization for smoother, more accurate terminal fills.
 - Built-in styling for progress bar fills, colors, gradients, and head glyphs.
 - Animated progress titles with a subtle sweeping highlight.
   Set `LOGBAR_ANIMATION=0` to disable the highlight animation.
@@ -52,6 +53,46 @@ pip install logbar
 
 LogBar works out-of-the-box with CPython 3.8+ on Linux, macOS, and Windows terminals.
 
+## Renderer Design
+
+LogBar keeps progress bars, spinners, tables, and normal log lines readable in the same terminal session. Compared with traditional loggers, it lets long-running CLI programs show live status without flooding the screen with repeated status lines or breaking the flow of regular logs.
+
+Main rendering APIs:
+
+- `log.pb(...)` for live progress bars
+- `log.spinner(...)` for work with no fixed total
+- `log.columns(...)` for aligned table output
+
+Examples:
+
+```py
+from logbar import LogBar
+
+log = LogBar.shared()
+
+for _ in log.pb(range(5)).title("下载 📦").subtitle("phase 1"):
+    pass
+```
+
+```py
+jobs = ["scan", "parse", "index", "flush"]
+pb = log.pb(jobs, output_interval=1).title("Indexing").manual()
+for job in pb:
+    log.info("processing %s", job)
+    pb.subtitle(job).draw()
+```
+
+```py
+cols = log.columns(
+    {"label": "task", "width": "fit"},
+    {"label": "status", "width": "fit"},
+    {"label": "detail", "width": "50%"},
+)
+
+cols.info.header()
+cols.info("render", "active", "width and alignment stay terminal-aware")
+```
+
 # Quick Start
 
 ```py
@@ -199,6 +240,28 @@ pb.head('>', color='82')  # custom head glyph + color index
 
 `ProgressBar.available_styles()` lists builtin styles, and you can register additional ones with `ProgressBar.register_style(...)` or switch defaults globally via `ProgressBar.set_default_style(...)`. Custom colors accept ANSI escape codes, 256-color indexes (e.g. `'82'`), or hex strings (`'#4c1d95'`).
 
+For direct style registration and introspection, import the advanced style APIs from `logbar.progress`:
+
+```py
+from logbar.progress import ProgressBar, ProgressStyle, progress_style_names
+
+print(ProgressBar.available_styles())
+print(progress_style_names())
+
+ProgressBar.register_style(
+    ProgressStyle(
+        name="ice",
+        fill_char="■",
+        empty_char="·",
+        fill_colors=("#7dd3fc", "#38bdf8"),
+        gradient=True,
+        head_char=">",
+    )
+)
+
+ProgressBar.set_default_style("ice")
+```
+
 Styled output (plain-text view with ANSI removed):
 
 ```
@@ -248,6 +311,14 @@ cols.update({
 })
 ```
 
+Useful column helpers:
+
+- `cols.info.header()` or `cols.info.headers()` prints the current border + header block.
+- `cols.info.simulate(...)` recomputes widths without emitting a row.
+- `cols.update(...)` changes labels, spans, or widths at runtime.
+- `cols.width()` returns the current rendered table width, including borders.
+- `cols.widths`, `cols.padding`, and `cols.column_specs` expose the current layout.
+
 # Replacing `tqdm`
 
 The API mirrors common `tqdm` patterns while staying more Pythonic:
@@ -275,7 +346,7 @@ with tqdm.tqdm(total=len(items)) as pb:
 with log.pb(items).manual() as pb:
     for item in pb:
         handle(item)
-        pb.render()
+        pb.draw()
 ```
 
 # Advanced Tips
@@ -283,3 +354,69 @@ with log.pb(items).manual() as pb:
 - Combine columns and progress bars by logging summaries at key checkpoints.
 - Use `log.warn.once(...)` to keep noisy health checks readable.
 - For multi-line messages, pre-format text and pass it as a single string; LogBar keeps borders intact.
+
+# API Reference
+
+## `LogBar`
+
+- `LogBar.shared(override_logger=False)` returns the process-wide shared logger.
+- `override_logger=True` is useful in tests or embedded environments that replaced the active `logging` logger class.
+- Level methods: `debug`, `info`, `warn`, `error`, `critical`.
+- Deduplicated level methods: `debug.once`, `info.once`, `warn.once`, `error.once`, `critical.once`.
+- `setLevel(level)` accepts strings like `"INFO"`, `"WARN"`, `"CRIT"`, numeric levels, numeric strings, and constants such as `LogBar.WARNING`.
+- `pb(iterable_or_total, output_interval=None)` creates and attaches a progress bar.
+- `spinner(title="", interval=0.5, tail_length=4)` creates and attaches an indeterminate rolling progress bar.
+- `columns(..., cols=None, width=None, padding=2)` creates a column printer.
+
+## `ProgressBar`
+
+`log.pb(...)` returns an attached `ProgressBar`. For direct imports, use:
+
+```py
+from logbar.progress import ProgressBar, ProgressStyle
+```
+
+Common chainable methods:
+
+- `title(text)` and `subtitle(text)`
+- `style(name_or_style)`
+- `fill(fill_char, empty=None)`
+- `colors(fill=None, empty=None, gradient=None, head=None)`
+- `head(char=None, color=None)`
+- `set(show_left_steps=None, left_steps_offset=None)`
+- `output_interval(interval)`
+- `mode(RenderMode)` if you prefer explicit mode switching over `auto()` / `manual()`
+
+Render and lifecycle control:
+
+- `draw(force=False)` renders the current snapshot immediately.
+- `auto()` enables redraw-on-iteration mode.
+- `manual()` disables automatic redraw so you can call `draw()` yourself.
+- `attach(logger=None)` attaches the bar to a logger.
+- `detach()` detaches the bar without destroying the object.
+- `close()` forces a final render if needed and removes the bar from the stack.
+- `step()` returns the current iteration index and `next()` advances once outside a `for` loop.
+
+Style registry helpers:
+
+- `ProgressBar.available_styles()`
+- `ProgressBar.register_style(style)`
+- `ProgressBar.set_default_style(style)`
+- `ProgressBar.default_style()`
+
+## `RollingProgressBar`
+
+`log.spinner(...)` returns a `RollingProgressBar`, which inherits from `ProgressBar` and adds:
+
+- `pulse()` to advance the spinner immediately between automatic ticks.
+- `interval` and `tail_length` constructor arguments for animation speed and tail size.
+
+## `ColumnsPrinter`
+
+`log.columns(...)` returns a `ColumnsPrinter` with per-level proxies:
+
+- `cols.info(...)`, `cols.warn(...)`, `cols.error(...)`, `cols.debug(...)`, `cols.critical(...)`
+- `cols.info.header()` and `cols.info.headers()` for border + header emission
+- `cols.info.simulate(...)` for dry-run width growth without output
+- `cols.update(...)` for runtime schema changes
+- `cols.width()` for the current rendered width

{logbar-0.2.4 → logbar-0.3.0}/LogBar.egg-info/SOURCES.txt

@@ -8,11 +8,14 @@ LogBar.egg-info/top_level.txt
 logbar/__init__.py
 logbar/buffer.py
 logbar/columns.py
+logbar/drawing.py
 logbar/logbar.py
 logbar/progress.py
 logbar/terminal.py
 logbar/util.py
 tests/test_columns.py
+tests/test_drawing.py
 tests/test_example.py
 tests/test_log.py
-tests/test_progress.py
+tests/test_progress.py
+tests/test_snake_render.py

{logbar-0.2.4 → logbar-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LogBar
-Version: 0.2.4
+Version: 0.3.0
 Summary: A unified Logger and ProgressBar util with zero dependencies.
 Author-email: ModelCloud <qubitium@modelcloud.ai>
 License-Expression: Apache-2.0
@@ -36,6 +36,7 @@ Dynamic: license-file
 - Shared singleton logger with per-level colorized output.
 - `once` helpers prevent duplicate log spam automatically.
 - Stackable progress bars that stay anchored while your logs flow freely.
+- Sub-cell Unicode bar rasterization for smoother, more accurate terminal fills.
 - Built-in styling for progress bar fills, colors, gradients, and head glyphs.
 - Animated progress titles with a subtle sweeping highlight.
   Set `LOGBAR_ANIMATION=0` to disable the highlight animation.
@@ -52,6 +53,46 @@ pip install logbar
 
 LogBar works out-of-the-box with CPython 3.8+ on Linux, macOS, and Windows terminals.
 
+## Renderer Design
+
+LogBar keeps progress bars, spinners, tables, and normal log lines readable in the same terminal session. Compared with traditional loggers, it lets long-running CLI programs show live status without flooding the screen with repeated status lines or breaking the flow of regular logs.
+
+Main rendering APIs:
+
+- `log.pb(...)` for live progress bars
+- `log.spinner(...)` for work with no fixed total
+- `log.columns(...)` for aligned table output
+
+Examples:
+
+```py
+from logbar import LogBar
+
+log = LogBar.shared()
+
+for _ in log.pb(range(5)).title("下载 📦").subtitle("phase 1"):
+    pass
+```
+
+```py
+jobs = ["scan", "parse", "index", "flush"]
+pb = log.pb(jobs, output_interval=1).title("Indexing").manual()
+for job in pb:
+    log.info("processing %s", job)
+    pb.subtitle(job).draw()
+```
+
+```py
+cols = log.columns(
+    {"label": "task", "width": "fit"},
+    {"label": "status", "width": "fit"},
+    {"label": "detail", "width": "50%"},
+)
+
+cols.info.header()
+cols.info("render", "active", "width and alignment stay terminal-aware")
+```
+
 # Quick Start
 
 ```py
@@ -199,6 +240,28 @@ pb.head('>', color='82')  # custom head glyph + color index
 
 `ProgressBar.available_styles()` lists builtin styles, and you can register additional ones with `ProgressBar.register_style(...)` or switch defaults globally via `ProgressBar.set_default_style(...)`. Custom colors accept ANSI escape codes, 256-color indexes (e.g. `'82'`), or hex strings (`'#4c1d95'`).
 
+For direct style registration and introspection, import the advanced style APIs from `logbar.progress`:
+
+```py
+from logbar.progress import ProgressBar, ProgressStyle, progress_style_names
+
+print(ProgressBar.available_styles())
+print(progress_style_names())
+
+ProgressBar.register_style(
+    ProgressStyle(
+        name="ice",
+        fill_char="■",
+        empty_char="·",
+        fill_colors=("#7dd3fc", "#38bdf8"),
+        gradient=True,
+        head_char=">",
+    )
+)
+
+ProgressBar.set_default_style("ice")
+```
+
 Styled output (plain-text view with ANSI removed):
 
 ```
@@ -248,6 +311,14 @@ cols.update({
 })
 ```
 
+Useful column helpers:
+
+- `cols.info.header()` or `cols.info.headers()` prints the current border + header block.
+- `cols.info.simulate(...)` recomputes widths without emitting a row.
+- `cols.update(...)` changes labels, spans, or widths at runtime.
+- `cols.width()` returns the current rendered table width, including borders.
+- `cols.widths`, `cols.padding`, and `cols.column_specs` expose the current layout.
+
 # Replacing `tqdm`
 
 The API mirrors common `tqdm` patterns while staying more Pythonic:
@@ -275,7 +346,7 @@ with tqdm.tqdm(total=len(items)) as pb:
 with log.pb(items).manual() as pb:
     for item in pb:
         handle(item)
-        pb.render()
+        pb.draw()
 ```
 
 # Advanced Tips
@@ -283,3 +354,69 @@ with log.pb(items).manual() as pb:
 - Combine columns and progress bars by logging summaries at key checkpoints.
 - Use `log.warn.once(...)` to keep noisy health checks readable.
 - For multi-line messages, pre-format text and pass it as a single string; LogBar keeps borders intact.
+
+# API Reference
+
+## `LogBar`
+
+- `LogBar.shared(override_logger=False)` returns the process-wide shared logger.
+- `override_logger=True` is useful in tests or embedded environments that replaced the active `logging` logger class.
+- Level methods: `debug`, `info`, `warn`, `error`, `critical`.
+- Deduplicated level methods: `debug.once`, `info.once`, `warn.once`, `error.once`, `critical.once`.
+- `setLevel(level)` accepts strings like `"INFO"`, `"WARN"`, `"CRIT"`, numeric levels, numeric strings, and constants such as `LogBar.WARNING`.
+- `pb(iterable_or_total, output_interval=None)` creates and attaches a progress bar.
+- `spinner(title="", interval=0.5, tail_length=4)` creates and attaches an indeterminate rolling progress bar.
+- `columns(..., cols=None, width=None, padding=2)` creates a column printer.
+
+## `ProgressBar`
+
+`log.pb(...)` returns an attached `ProgressBar`. For direct imports, use:
+
+```py
+from logbar.progress import ProgressBar, ProgressStyle
+```
+
+Common chainable methods:
+
+- `title(text)` and `subtitle(text)`
+- `style(name_or_style)`
+- `fill(fill_char, empty=None)`
+- `colors(fill=None, empty=None, gradient=None, head=None)`
+- `head(char=None, color=None)`
+- `set(show_left_steps=None, left_steps_offset=None)`
+- `output_interval(interval)`
+- `mode(RenderMode)` if you prefer explicit mode switching over `auto()` / `manual()`
+
+Render and lifecycle control:
+
+- `draw(force=False)` renders the current snapshot immediately.
+- `auto()` enables redraw-on-iteration mode.
+- `manual()` disables automatic redraw so you can call `draw()` yourself.
+- `attach(logger=None)` attaches the bar to a logger.
+- `detach()` detaches the bar without destroying the object.
+- `close()` forces a final render if needed and removes the bar from the stack.
+- `step()` returns the current iteration index and `next()` advances once outside a `for` loop.
+
+Style registry helpers:
+
+- `ProgressBar.available_styles()`
+- `ProgressBar.register_style(style)`
+- `ProgressBar.set_default_style(style)`
+- `ProgressBar.default_style()`
+
+## `RollingProgressBar`
+
+`log.spinner(...)` returns a `RollingProgressBar`, which inherits from `ProgressBar` and adds:
+
+- `pulse()` to advance the spinner immediately between automatic ticks.
+- `interval` and `tail_length` constructor arguments for animation speed and tail size.
+
+## `ColumnsPrinter`
+
+`log.columns(...)` returns a `ColumnsPrinter` with per-level proxies:
+
+- `cols.info(...)`, `cols.warn(...)`, `cols.error(...)`, `cols.debug(...)`, `cols.critical(...)`
+- `cols.info.header()` and `cols.info.headers()` for border + header emission
+- `cols.info.simulate(...)` for dry-run width growth without output
+- `cols.update(...)` for runtime schema changes
+- `cols.width()` for the current rendered width

{logbar-0.2.4 → logbar-0.3.0}/README.md

@@ -21,6 +21,7 @@
 - Shared singleton logger with per-level colorized output.
 - `once` helpers prevent duplicate log spam automatically.
 - Stackable progress bars that stay anchored while your logs flow freely.
+- Sub-cell Unicode bar rasterization for smoother, more accurate terminal fills.
 - Built-in styling for progress bar fills, colors, gradients, and head glyphs.
 - Animated progress titles with a subtle sweeping highlight.
   Set `LOGBAR_ANIMATION=0` to disable the highlight animation.
@@ -37,6 +38,46 @@ pip install logbar
 
 LogBar works out-of-the-box with CPython 3.8+ on Linux, macOS, and Windows terminals.
 
+## Renderer Design
+
+LogBar keeps progress bars, spinners, tables, and normal log lines readable in the same terminal session. Compared with traditional loggers, it lets long-running CLI programs show live status without flooding the screen with repeated status lines or breaking the flow of regular logs.
+
+Main rendering APIs:
+
+- `log.pb(...)` for live progress bars
+- `log.spinner(...)` for work with no fixed total
+- `log.columns(...)` for aligned table output
+
+Examples:
+
+```py
+from logbar import LogBar
+
+log = LogBar.shared()
+
+for _ in log.pb(range(5)).title("下载 📦").subtitle("phase 1"):
+    pass
+```
+
+```py
+jobs = ["scan", "parse", "index", "flush"]
+pb = log.pb(jobs, output_interval=1).title("Indexing").manual()
+for job in pb:
+    log.info("processing %s", job)
+    pb.subtitle(job).draw()
+```
+
+```py
+cols = log.columns(
+    {"label": "task", "width": "fit"},
+    {"label": "status", "width": "fit"},
+    {"label": "detail", "width": "50%"},
+)
+
+cols.info.header()
+cols.info("render", "active", "width and alignment stay terminal-aware")
+```
+
 # Quick Start
 
 ```py
@@ -184,6 +225,28 @@ pb.head('>', color='82')  # custom head glyph + color index
 
 `ProgressBar.available_styles()` lists builtin styles, and you can register additional ones with `ProgressBar.register_style(...)` or switch defaults globally via `ProgressBar.set_default_style(...)`. Custom colors accept ANSI escape codes, 256-color indexes (e.g. `'82'`), or hex strings (`'#4c1d95'`).
 
+For direct style registration and introspection, import the advanced style APIs from `logbar.progress`:
+
+```py
+from logbar.progress import ProgressBar, ProgressStyle, progress_style_names
+
+print(ProgressBar.available_styles())
+print(progress_style_names())
+
+ProgressBar.register_style(
+    ProgressStyle(
+        name="ice",
+        fill_char="■",
+        empty_char="·",
+        fill_colors=("#7dd3fc", "#38bdf8"),
+        gradient=True,
+        head_char=">",
+    )
+)
+
+ProgressBar.set_default_style("ice")
+```
+
 Styled output (plain-text view with ANSI removed):
 
 ```
@@ -233,6 +296,14 @@ cols.update({
 })
 ```
 
+Useful column helpers:
+
+- `cols.info.header()` or `cols.info.headers()` prints the current border + header block.
+- `cols.info.simulate(...)` recomputes widths without emitting a row.
+- `cols.update(...)` changes labels, spans, or widths at runtime.
+- `cols.width()` returns the current rendered table width, including borders.
+- `cols.widths`, `cols.padding`, and `cols.column_specs` expose the current layout.
+
 # Replacing `tqdm`
 
 The API mirrors common `tqdm` patterns while staying more Pythonic:
@@ -260,7 +331,7 @@ with tqdm.tqdm(total=len(items)) as pb:
 with log.pb(items).manual() as pb:
     for item in pb:
         handle(item)
-        pb.render()
+        pb.draw()
 ```
 
 # Advanced Tips
@@ -268,3 +339,69 @@ with log.pb(items).manual() as pb:
 - Combine columns and progress bars by logging summaries at key checkpoints.
 - Use `log.warn.once(...)` to keep noisy health checks readable.
 - For multi-line messages, pre-format text and pass it as a single string; LogBar keeps borders intact.
+
+# API Reference
+
+## `LogBar`
+
+- `LogBar.shared(override_logger=False)` returns the process-wide shared logger.
+- `override_logger=True` is useful in tests or embedded environments that replaced the active `logging` logger class.
+- Level methods: `debug`, `info`, `warn`, `error`, `critical`.
+- Deduplicated level methods: `debug.once`, `info.once`, `warn.once`, `error.once`, `critical.once`.
+- `setLevel(level)` accepts strings like `"INFO"`, `"WARN"`, `"CRIT"`, numeric levels, numeric strings, and constants such as `LogBar.WARNING`.
+- `pb(iterable_or_total, output_interval=None)` creates and attaches a progress bar.
+- `spinner(title="", interval=0.5, tail_length=4)` creates and attaches an indeterminate rolling progress bar.
+- `columns(..., cols=None, width=None, padding=2)` creates a column printer.
+
+## `ProgressBar`
+
+`log.pb(...)` returns an attached `ProgressBar`. For direct imports, use:
+
+```py
+from logbar.progress import ProgressBar, ProgressStyle
+```
+
+Common chainable methods:
+
+- `title(text)` and `subtitle(text)`
+- `style(name_or_style)`
+- `fill(fill_char, empty=None)`
+- `colors(fill=None, empty=None, gradient=None, head=None)`
+- `head(char=None, color=None)`
+- `set(show_left_steps=None, left_steps_offset=None)`
+- `output_interval(interval)`
+- `mode(RenderMode)` if you prefer explicit mode switching over `auto()` / `manual()`
+
+Render and lifecycle control:
+
+- `draw(force=False)` renders the current snapshot immediately.
+- `auto()` enables redraw-on-iteration mode.
+- `manual()` disables automatic redraw so you can call `draw()` yourself.
+- `attach(logger=None)` attaches the bar to a logger.
+- `detach()` detaches the bar without destroying the object.
+- `close()` forces a final render if needed and removes the bar from the stack.
+- `step()` returns the current iteration index and `next()` advances once outside a `for` loop.
+
+Style registry helpers:
+
+- `ProgressBar.available_styles()`
+- `ProgressBar.register_style(style)`
+- `ProgressBar.set_default_style(style)`
+- `ProgressBar.default_style()`
+
+## `RollingProgressBar`
+
+`log.spinner(...)` returns a `RollingProgressBar`, which inherits from `ProgressBar` and adds:
+
+- `pulse()` to advance the spinner immediately between automatic ticks.
+- `interval` and `tail_length` constructor arguments for animation speed and tail size.
+
+## `ColumnsPrinter`
+
+`log.columns(...)` returns a `ColumnsPrinter` with per-level proxies:
+
+- `cols.info(...)`, `cols.warn(...)`, `cols.error(...)`, `cols.debug(...)`, `cols.critical(...)`
+- `cols.info.header()` and `cols.info.headers()` for border + header emission
+- `cols.info.simulate(...)` for dry-run width growth without output
+- `cols.update(...)` for runtime schema changes
+- `cols.width()` for the current rendered width

{logbar-0.2.4 → logbar-0.3.0}/logbar/columns.py

@@ -5,28 +5,14 @@
 
 """Column layout helpers for LogBar output."""
 
-import re
 from dataclasses import dataclass
 from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, Union
 
+from .drawing import strip_ansi as _strip_ansi
+from .drawing import visible_length as _visible_length
 from .terminal import terminal_size
 
 
-ANSI_ESCAPE_RE = re.compile(r"\x1B\[[0-9;?]*[ -/]*[@-~]")
-
-
-def _strip_ansi(text: str) -> str:
-    return ANSI_ESCAPE_RE.sub("", text)
-
-
-def _visible_length(text: str) -> int:
-    if not text:
-        return 0
-    cleaned = _strip_ansi(text)
-    cleaned = cleaned.replace("\r", "").replace("\n", "")
-    return len(cleaned)
-
-
 def _pad_visible(text: str, target: int) -> str:
     current = _visible_length(text)
     if current >= target: