processit 0.2.0__tar.gz → 0.2.2__tar.gz

{processit-0.2.0/src/processit.egg-info → processit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processit
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lightweight progress utilities for sync/async workloads
 Author: Vicente Ruiz
 License-Expression: MIT
@@ -79,8 +79,9 @@ def numbers():
 
 async def main():
     async with progress(numbers(), total=10, desc='Numbers') as p:
+        log = p.log_stream()
         async for n in p:
-            p.write(f'value: {n}')
+            print(f'value: {n}', file=log)
             await asyncio.sleep(0.5)
 
 asyncio.run(main())
@@ -181,6 +182,23 @@ Need concurrency limit `Semaphore` + `track_as_completed(...)`
 
 ---
 
+### 3. TTY vs non-TTY output
+
+When the output stream is a real TTY, `processit` redraws the same line.
+
+When the output stream is not a TTY (for example CI logs, redirected output,
+or `StringIO` in tests), `processit` emits line-based snapshots instead:
+
+- It respects `refresh_interval` without periodic duplicate frames
+- It prints a final `100%` snapshot before the summary when `total` is known
+- Messages written with `p.write(...)` or `file=p.log_stream()` stay above the
+  live bar; the bar is re-rendered as the last line in TTY mode
+
+Timing starts when iteration actually begins, not when the `Progress`
+instance is created.
+
+---
+
 ## More Examples
 
 ### Asynchronous iteration over a data source
@@ -250,6 +268,17 @@ Name Type Description
 
 ---
 
+### Progress helpers inside `async with progress(...) as p`
+
+- `p.write("message")`: prints a message above the live bar and re-renders it
+- `p.log_stream()`: returns a file-like stream for `print(..., file=...)` or
+  `logging.StreamHandler`
+
+If a command mixes progress output with logs, prefer one of those two
+interfaces instead of calling `print(...)` directly on stdout/stderr.
+
+---
+
 ### track_as_completed(tasks, total=None, \*, desc='Processing', width=30, refresh_interval=0.1, show_summary=True)
 
 Tracks a collection of awaitables or tasks as they complete.

{processit-0.2.0 → processit-0.2.2}/README.md

@@ -58,8 +58,9 @@ def numbers():
 
 async def main():
     async with progress(numbers(), total=10, desc='Numbers') as p:
+        log = p.log_stream()
         async for n in p:
-            p.write(f'value: {n}')
+            print(f'value: {n}', file=log)
             await asyncio.sleep(0.5)
 
 asyncio.run(main())
@@ -160,6 +161,23 @@ Need concurrency limit `Semaphore` + `track_as_completed(...)`
 
 ---
 
+### 3. TTY vs non-TTY output
+
+When the output stream is a real TTY, `processit` redraws the same line.
+
+When the output stream is not a TTY (for example CI logs, redirected output,
+or `StringIO` in tests), `processit` emits line-based snapshots instead:
+
+- It respects `refresh_interval` without periodic duplicate frames
+- It prints a final `100%` snapshot before the summary when `total` is known
+- Messages written with `p.write(...)` or `file=p.log_stream()` stay above the
+  live bar; the bar is re-rendered as the last line in TTY mode
+
+Timing starts when iteration actually begins, not when the `Progress`
+instance is created.
+
+---
+
 ## More Examples
 
 ### Asynchronous iteration over a data source
@@ -229,6 +247,17 @@ Name Type Description
 
 ---
 
+### Progress helpers inside `async with progress(...) as p`
+
+- `p.write("message")`: prints a message above the live bar and re-renders it
+- `p.log_stream()`: returns a file-like stream for `print(..., file=...)` or
+  `logging.StreamHandler`
+
+If a command mixes progress output with logs, prefer one of those two
+interfaces instead of calling `print(...)` directly on stdout/stderr.
+
+---
+
 ### track_as_completed(tasks, total=None, \*, desc='Processing', width=30, refresh_interval=0.1, show_summary=True)
 
 Tracks a collection of awaitables or tasks as they complete.

processit-0.2.2/src/processit/_version.py

@@ -0,0 +1,2 @@
+version_info: tuple[int | str, ...] = (0, 2, 2)
+__version__ = '.'.join(map(str, version_info))

{processit-0.2.0 → processit-0.2.2}/src/processit/progress.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import io
 import sys
 import time
 
@@ -18,14 +19,68 @@ if TYPE_CHECKING:
     )
 
 
+class _ProgressLogStream(io.TextIOBase):
+    __slots__ = ('_buffer', '_progress')
+
+    def __init__(self, progress: Progress[object]) -> None:
+        self._progress = progress
+        self._buffer = ''
+
+    @property
+    def encoding(self) -> str | None:
+        return getattr(self._progress.stream, 'encoding', None)
+
+    def isatty(self) -> bool:
+        return self._progress._is_tty
+
+    def writable(self) -> bool:
+        return True
+
+    def write(self, msg: str) -> int:
+        if not isinstance(msg, str):
+            msg = str(msg)
+
+        if not msg:
+            return 0
+
+        self._buffer += msg
+        self._flush_complete_lines()
+        return len(msg)
+
+    def flush(self) -> None:
+        self.flush_pending()
+
+    def close(self) -> None:
+        self.flush()
+
+    def flush_pending(self) -> None:
+        if not self._buffer:
+            return
+
+        pending = self._buffer.removesuffix('\r')
+        self._buffer = ''
+        self._progress._write_message(pending, allow_blank=True)
+
+    def _flush_complete_lines(self) -> None:
+        while '\n' in self._buffer:
+            line, self._buffer = self._buffer.split('\n', 1)
+            self._progress._write_message(
+                line.removesuffix('\r'),
+                allow_blank=True,
+            )
+
+
 class Progress[T]:
     __slots__ = (
         '_is_tty',
         '_last_line_len',
         '_last_refresh',
+        '_last_render_count',
+        '_log_stream',
         '_next_render_at',
         '_prefix',
         '_refresh_task',
+        '_started',
         '_stopped',
         '_summary_printed',
         'count',
@@ -65,22 +120,58 @@ class Progress[T]:
         self._refresh_task: asyncio.Task[None] | None = None
         self._summary_printed = False
         self._last_line_len = 0
+        self._last_render_count = 0
+        self._started = False
         self._stopped = False
         self._is_tty = bool(getattr(self.stream, 'isatty', lambda: False)())
+        self._log_stream: _ProgressLogStream | None = None
         self._prefix = f'{self.desc} '
 
+    def _start_rendering(self) -> None:
+        self._started = True
+        self._stopped = False
+        self.start_time = time.perf_counter()
+        self._last_refresh = 0.0
+        self._next_render_at = 0.0
+        self._last_line_len = 0
+        self._last_render_count = -1
+        self._render(force=True)
+        if self._is_tty:
+            self._refresh_task = asyncio.create_task(
+                self._refresh_periodically(),
+            )
+
     def write(self, msg: str = '') -> None:
-        """Print a message below the bar and re-render it (TTY-safe)."""
+        """Print a message above the live bar and re-render it."""
+        self._write_message(msg)
+
+    def log_stream(self) -> TextIO:
+        """Return a file-like stream that logs above the live bar."""
+        if self._log_stream is None:
+            progress = cast('Progress[object]', self)
+            self._log_stream = _ProgressLogStream(progress)
+        return cast('TextIO', self._log_stream)
+
+    def _write_message(
+        self,
+        msg: str = '',
+        *,
+        allow_blank: bool = False,
+    ) -> None:
         if self._stopped:
             return
         self._clear_line()
-        if msg:
+        if msg or allow_blank:
             if not msg.endswith('\n'):
                 msg += '\n'
             self.stream.write(msg)
             self.stream.flush()
         self._render(force=True)
 
+    def _flush_log_stream(self) -> None:
+        if self._log_stream is not None:
+            self._log_stream.flush_pending()
+
     async def amap[R](
         self,
         mapper: Callable[[T], Awaitable[R]],
@@ -143,12 +234,8 @@ class Progress[T]:
         # Start the refresh task if it hasn't been started
         # yet (same as in __aiter__)
         started_here = False
-        if self._refresh_task is None:
-            self._stopped = False
-            self._render(force=True)
-            self._refresh_task = asyncio.create_task(
-                self._refresh_periodically(),
-            )
+        if not self._started:
+            self._start_rendering()
             started_here = True
 
         try:
@@ -195,6 +282,7 @@ class Progress[T]:
                     await self._refresh_task
                 self._refresh_task = None
             self._print_summary_if_needed()
+            self._started = False
 
     def _format_elapsed(self, seconds: float) -> str:
         """Return hh:mm:ss, mm:ss or ss.s depending on duration."""
@@ -217,7 +305,7 @@ class Progress[T]:
             # tests/logs
             self.stream.write(text + '\n')
             self.stream.flush()
-            self._last_line_len = 0
+            self._last_line_len = len(text)
 
     def _clear_line(self) -> None:
         if self._is_tty:
@@ -268,11 +356,19 @@ class Progress[T]:
             )
 
         self._write_line(line)
+        self._last_render_count = self.count
         self._last_refresh = now
         self._next_render_at = now + self.refresh_interval
 
     def _print_summary_if_needed(self) -> None:
+        self._flush_log_stream()
         if self.show_summary and not self._summary_printed:
+            if (
+                self.total is not None
+                and self.count == self.total
+                and self._last_render_count != self.count
+            ):
+                self._render(force=True)
             self._stopped = True
             self._clear_line()
 
@@ -295,9 +391,8 @@ class Progress[T]:
             self._render()
 
     async def __aenter__(self) -> Progress[T]:
-        self._stopped = False
-        self._render(force=True)  # feedback inmediato
-        self._refresh_task = asyncio.create_task(self._refresh_periodically())
+        if not self._started:
+            self._start_rendering()  # feedback inmediato
         return self
 
     async def __aexit__(self, *_: object) -> None:
@@ -307,18 +402,14 @@ class Progress[T]:
                 await self._refresh_task
             self._refresh_task = None
         self._print_summary_if_needed()
+        self._started = False
 
     async def __aiter__(self) -> AsyncIterator[T]:
         started_here = False
 
-        if self._refresh_task is None:
-            self._stopped = False
-            self._render(
-                force=True,
-            )  # feedback inmediato fuera de context manager
-            self._refresh_task = asyncio.create_task(
-                self._refresh_periodically(),
-            )
+        if not self._started:
+            # feedback inmediato fuera de context manager
+            self._start_rendering()
             started_here = True
 
         try:
@@ -341,6 +432,7 @@ class Progress[T]:
                     await self._refresh_task
                 self._refresh_task = None
             self._print_summary_if_needed()
+            self._started = False
 
 
 def progress[T](  # noqa: PLR0913

{processit-0.2.0 → processit-0.2.2/src/processit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processit
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lightweight progress utilities for sync/async workloads
 Author: Vicente Ruiz
 License-Expression: MIT
@@ -79,8 +79,9 @@ def numbers():
 
 async def main():
     async with progress(numbers(), total=10, desc='Numbers') as p:
+        log = p.log_stream()
         async for n in p:
-            p.write(f'value: {n}')
+            print(f'value: {n}', file=log)
             await asyncio.sleep(0.5)
 
 asyncio.run(main())
@@ -181,6 +182,23 @@ Need concurrency limit `Semaphore` + `track_as_completed(...)`
 
 ---
 
+### 3. TTY vs non-TTY output
+
+When the output stream is a real TTY, `processit` redraws the same line.
+
+When the output stream is not a TTY (for example CI logs, redirected output,
+or `StringIO` in tests), `processit` emits line-based snapshots instead:
+
+- It respects `refresh_interval` without periodic duplicate frames
+- It prints a final `100%` snapshot before the summary when `total` is known
+- Messages written with `p.write(...)` or `file=p.log_stream()` stay above the
+  live bar; the bar is re-rendered as the last line in TTY mode
+
+Timing starts when iteration actually begins, not when the `Progress`
+instance is created.
+
+---
+
 ## More Examples
 
 ### Asynchronous iteration over a data source
@@ -250,6 +268,17 @@ Name Type Description
 
 ---
 
+### Progress helpers inside `async with progress(...) as p`
+
+- `p.write("message")`: prints a message above the live bar and re-renders it
+- `p.log_stream()`: returns a file-like stream for `print(..., file=...)` or
+  `logging.StreamHandler`
+
+If a command mixes progress output with logs, prefer one of those two
+interfaces instead of calling `print(...)` directly on stdout/stderr.
+
+---
+
 ### track_as_completed(tasks, total=None, \*, desc='Processing', width=30, refresh_interval=0.1, show_summary=True)
 
 Tracks a collection of awaitables or tasks as they complete.

{processit-0.2.0 → processit-0.2.2}/tests/test_progress.py

@@ -34,6 +34,49 @@ def _last_nonempty_line(buf: str) -> str:
     return ''
 
 
+class _TTYStringIO(io.StringIO):
+    def isatty(self) -> bool:
+        return True
+
+
+def _render_tty_screen(buf: str) -> list[str]:
+    lines: list[str] = []
+    current: list[str] = []
+    cursor = 0
+    idx = 0
+
+    while idx < len(buf):
+        if buf.startswith('\x1b[2K', idx):
+            current = []
+            cursor = 0
+            idx += 4
+            continue
+
+        char = buf[idx]
+        idx += 1
+
+        if char == '\r':
+            cursor = 0
+            continue
+
+        if char == '\n':
+            lines.append(''.join(current))
+            current = []
+            cursor = 0
+            continue
+
+        if cursor == len(current):
+            current.append(char)
+        else:
+            current[cursor] = char
+        cursor += 1
+
+    if current:
+        lines.append(''.join(current))
+
+    return [line for line in lines if line.strip()]
+
+
 # -----------------------------
 # Synchronous iterable cases
 # -----------------------------
@@ -64,6 +107,107 @@ async def test_sync_iterable_basic_summary_only_once():
     assert 'it/s' in out
 
 
+@pytest.mark.asyncio
+async def test_non_tty_respects_refresh_interval():
+    stream = io.StringIO()
+    expected_bar_frames = 2
+
+    def numbers() -> Iterator[int]:
+        for i in range(20):
+            time.sleep(0.005)
+            yield i
+
+    async for _ in progress(
+        numbers(),
+        desc='NonTTY',
+        total=20,
+        stream=stream,
+        refresh_interval=10.0,
+    ):
+        await asyncio.sleep(0)
+
+    out = _strip_ansi(stream.getvalue())
+    assert out.count('NonTTY [') == expected_bar_frames
+    assert 'NonTTY [##############################] 100.00% (20/20)' in out
+    assert out.count('NonTTY: 20 it in ') == 1
+
+
+@pytest.mark.asyncio
+async def test_non_tty_renders_final_complete_frame_before_summary():
+    stream = io.StringIO()
+    data = list(range(3))
+
+    async for _ in progress(
+        data,
+        desc='Final',
+        total=3,
+        stream=stream,
+        refresh_interval=10.0,
+    ):
+        await asyncio.sleep(0)
+
+    lines = [
+        line for line in _strip_ansi(stream.getvalue()).splitlines() if line
+    ]
+    expected_complete = 'Final [##############################] 100.00% (3/3)'
+    assert any(expected_complete in line for line in lines)
+    assert lines[-1].startswith('Final: 3 it in ')
+
+
+@pytest.mark.asyncio
+async def test_non_tty_async_iterable_does_not_duplicate_periodic_frames():
+    stream = io.StringIO()
+    expected_lines = 5
+
+    async def agen() -> AsyncIterator[int]:
+        for i in range(3):
+            await asyncio.sleep(0.01)
+            yield i
+
+    async for _ in progress(
+        agen(),
+        desc='NoDupes',
+        total=3,
+        stream=stream,
+        refresh_interval=0.005,
+    ):
+        await asyncio.sleep(0)
+
+    lines = [
+        line for line in _strip_ansi(stream.getvalue()).splitlines() if line
+    ]
+    assert len(lines) == expected_lines
+    assert sum('(0/3)' in line for line in lines) == 1
+    assert sum('(1/3)' in line for line in lines) == 1
+    assert sum('(2/3)' in line for line in lines) == 1
+    assert sum('(3/3)' in line for line in lines) == 1
+    assert lines[-1].startswith('NoDupes: 3 it in ')
+
+
+@pytest.mark.asyncio
+async def test_elapsed_starts_on_first_use_not_object_creation():
+    stream = io.StringIO()
+    p = progress(
+        [1],
+        total=1,
+        desc='Delay',
+        stream=stream,
+        refresh_interval=10.0,
+    )
+
+    await asyncio.sleep(0.2)
+
+    async for _ in p:
+        await asyncio.sleep(0)
+
+    out = _strip_ansi(stream.getvalue())
+    expected_initial = (
+        'Delay [..............................]   0.00% (0/1) 0.00 it/s 00.0s'
+    )
+    assert expected_initial in out
+    assert 'Delay: 1 it in 00.0s' in out
+
+
 @pytest.mark.asyncio
 async def test_sync_iterable_infers_total_from_len():
     stream = io.StringIO()
@@ -72,9 +216,9 @@ async def test_sync_iterable_infers_total_from_len():
         data,
         desc='Len inf',
         stream=stream,
-        refresh_interval=1.0,
+        refresh_interval=0.001,
     ):
-        await asyncio.sleep(0)
+        await asyncio.sleep(0.01)
     out = stream.getvalue()
     # En algún render debe aparecer (4/4)
     assert '(4/4)' in out
@@ -164,6 +308,60 @@ async def test_async_with_and_write_no_extra_bar_at_end():
     assert 'With [' not in last
 
 
+@pytest.mark.asyncio
+async def test_log_stream_flushes_partial_output_before_summary_non_tty():
+    stream = io.StringIO()
+
+    async with progress(
+        [1, 2],
+        total=2,
+        desc='Stream',
+        stream=stream,
+        refresh_interval=10.0,
+    ) as p:
+        log = p.log_stream()
+        print('alpha', file=log)
+        log.write('beta')
+
+        async for _ in p:
+            await asyncio.sleep(0)
+
+    lines = [
+        line for line in _strip_ansi(stream.getvalue()).splitlines() if line
+    ]
+    assert 'alpha' in lines
+    assert 'beta' in lines
+    assert lines[-1].startswith('Stream: 2 it in ')
+    assert lines.index('alpha') < lines.index('beta') < len(lines) - 1
+
+
+@pytest.mark.asyncio
+async def test_log_stream_keeps_messages_above_bar_in_tty():
+    stream = _TTYStringIO()
+
+    async with progress(
+        [1, 2],
+        total=2,
+        desc='TTY',
+        stream=stream,
+        refresh_interval=10.0,
+    ) as p:
+        log = p.log_stream()
+        print('alpha', file=log)
+        log.write('beta')
+
+        async for _ in p:
+            await asyncio.sleep(0)
+
+    raw = stream.getvalue()
+    screen = _render_tty_screen(raw)
+
+    assert 'alpha\n\r\x1b[2KTTY [' in raw
+    assert 'beta\n\r\x1b[2KTTY [' in raw
+    assert screen[:-1] == ['alpha', 'beta']
+    assert screen[-1].startswith('TTY: 2 it in ')
+
+
 # -----------------------------
 # track_as_completed cases
 # -----------------------------
@@ -312,18 +510,18 @@ async def test_eta_only_when_total_known():
         total=3,
         desc='HasTotal',
         stream=stream1,
-        refresh_interval=1.0,
+        refresh_interval=0.001,
     ):
-        pass
+        await asyncio.sleep(0.01)
 
     # Sin total -> preferimos que no aparezca "ETA" en la salida
     async for _ in progress(
         agen(),
         desc='NoTotal',
         stream=stream2,
-        refresh_interval=1.0,
+        refresh_interval=0.001,
     ):
-        pass
+        await asyncio.sleep(0.01)
 
     out1 = stream1.getvalue()
     out2 = stream2.getvalue()

processit-0.2.0/src/processit/_version.py

@@ -1,2 +0,0 @@
-version_info: tuple[int | str, ...] = (0, 2, 0)
-__version__ = '.'.join(map(str, version_info))