outwrite 0.1.0a1__py3-none-any.whl

outwrite/__init__.py

@@ -0,0 +1,5 @@
+"""Standard logging and one live status line, across processes."""
+
+from ._output import OutputConnection, setup_output, status
+
+__all__ = ["OutputConnection", "setup_output", "status"]

outwrite/_output.py

@@ -0,0 +1,221 @@
+"""Parent rendering and worker connections."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import multiprocessing as mp
+import os
+import sys
+import threading
+import traceback
+from dataclasses import dataclass
+from logging.handlers import QueueHandler
+from multiprocessing.context import BaseContext
+from multiprocessing.queues import Queue
+from types import TracebackType
+
+from rich.console import Console
+from rich.live import Live
+from rich.logging import RichHandler
+from rich.text import Text
+
+_connection: OutputConnection | None = None
+_session: _OutputSession | None = None
+
+
+class _Status:
+    """Send text to the active session's status line."""
+
+    def update(self, text: str | None) -> None:
+        """Replace the status text. None or an empty string clears it."""
+        if text is not None and not isinstance(text, str):
+            raise TypeError("Status text must be a string or None.")
+        if _connection is None:
+            raise RuntimeError("Call setup_output() before updating status.")
+        if _connection._show_status:
+            _connection._queue.put("" if text is None else text)
+
+    def clear(self) -> None:
+        """Clear the status line without ending the output session."""
+        self.update(None)
+
+
+status = _Status()
+
+
+@dataclass(frozen=True)
+class OutputConnection:
+    """Pass this handle to workers; use it as a context manager in the parent."""
+
+    _queue: Queue
+    _logger_name: str
+    _show_status: bool
+    _parent_pid: int
+
+    def __enter__(self) -> OutputConnection:
+        if os.getpid() != self._parent_pid:
+            raise RuntimeError(
+                "Only the parent owns the output context; use setup_output(output) in workers."
+            )
+        if _session is None or _session.connection is not self:
+            raise RuntimeError("This output session is no longer active.")
+        if _session.entered:
+            raise RuntimeError("An output context cannot be nested.")
+        _session.entered = True
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        exc_traceback: TracebackType | None,
+    ) -> None:
+        if _session is None or _session.connection is not self:
+            raise RuntimeError("This output session is no longer active.")
+        _session.close()
+
+
+class _OutputSession:
+    """Own everything that must remain in the rendering process."""
+
+    def __init__(
+        self,
+        connection: OutputConnection,
+        logger: logging.Logger,
+        console: Console,
+        level: int,
+    ) -> None:
+        self.connection = connection
+        self.logger = logger
+        self.console = console
+        self.previous_handlers = logger.handlers[:]
+        self.previous_level = logger.level
+        self.previous_propagate = logger.propagate
+        self.console_handler = RichHandler(console=console, level=level)
+        self.handlers = [*self.previous_handlers, self.console_handler]
+        self.queue_handler = QueueHandler(connection._queue)
+        self.live = Live(
+            console=console,
+            transient=True,
+            auto_refresh=False,
+            redirect_stdout=False,
+            redirect_stderr=False,
+        )
+        self.error: Exception | None = None
+        self.entered = False
+        self.listener = threading.Thread(
+            target=self.listen, name="outwrite-renderer", daemon=True
+        )
+
+    def listen(self) -> None:
+        while True:
+            try:
+                message = self.connection._queue.get()
+            except (EOFError, OSError) as error:
+                self.error = error
+                traceback.print_exception(error, file=sys.stderr)
+                return
+            if message is None:
+                return
+            try:
+                if isinstance(message, logging.LogRecord):
+                    for handler in self.handlers:
+                        if message.levelno >= handler.level:
+                            handler.handle(message)
+                elif not message:
+                    self.live.stop()
+                else:
+                    text = Text(
+                        message, style="cyan", no_wrap=True, overflow="ellipsis"
+                    )
+                    text.truncate(max(1, self.console.width - 2), overflow="ellipsis")
+                    self.live.update(text, refresh=self.live.is_started)
+                    if not self.live.is_started:
+                        self.live.start(refresh=True)
+            except Exception as error:
+                # Keep draining so producers cannot deadlock behind a failed renderer.
+                self.error = error
+                traceback.print_exception(error, file=sys.stderr)
+
+    def close(self) -> None:
+        global _connection, _session
+        self.logger.handlers = self.previous_handlers
+        self.logger.setLevel(self.previous_level)
+        self.logger.propagate = self.previous_propagate
+        _connection = None
+        try:
+            self.connection._queue.put(None)
+            self.listener.join()
+        finally:
+            self.live.stop()
+            self.connection._queue.close()
+            self.connection._queue.join_thread()
+            self.queue_handler.close()
+            self.console_handler.close()
+            _session = None
+            atexit.unregister(_cleanup_at_exit)
+        if self.error is not None:
+            raise RuntimeError(
+                "Outwrite could not render one or more messages."
+            ) from self.error
+
+
+def setup_output(
+    connection: OutputConnection | None = None,
+    *,
+    logger: logging.Logger | None = None,
+    level: int = logging.INFO,
+    show_status: bool = True,
+    mp_context: BaseContext | None = None,
+) -> OutputConnection:
+    """Start a parent session, or connect a worker to the parent's session.
+
+    Parent usage: ``with setup_output(logger=my_logger) as output: ...``.
+    Join workers and logging threads before leaving the block.
+    Worker usage: ``setup_output(output)`` before logging or updating status.
+    Worker configuration comes from the connection, not the keyword options.
+    """
+    global _connection, _session
+    if _connection is not None:
+        raise RuntimeError("Output is already configured in this process.")
+    if connection is not None:
+        if connection._parent_pid == os.getpid():
+            raise RuntimeError(
+                "The parent is already responsible for rendering this connection."
+            )
+        worker_logger = logging.getLogger(connection._logger_name)
+        worker_logger.handlers = [QueueHandler(connection._queue)]
+        worker_logger.setLevel(logging.DEBUG)
+        worker_logger.propagate = False
+        _connection = connection
+        return connection
+
+    if logger is None:
+        logger = logging.getLogger("outwrite")
+    if logger is logging.getLogger():
+        raise ValueError("Choose a named logger, not the root logger.")
+    if not isinstance(level, int):
+        raise TypeError("level must be an integer logging level, such as logging.INFO.")
+    context = mp_context if mp_context is not None else mp.get_context("spawn")
+    if context.get_start_method() == "fork":
+        raise ValueError("Use a spawn or forkserver multiprocessing context, not fork.")
+
+    console = Console(stderr=True)
+    connection = OutputConnection(
+        context.Queue(), logger.name, show_status and console.is_terminal, os.getpid()
+    )
+    session = _OutputSession(connection, logger, console, level)
+    logger.handlers = [session.queue_handler]
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+    _connection = connection
+    _session = session
+    session.listener.start()
+    atexit.register(_cleanup_at_exit)
+    return connection
+
+
+def _cleanup_at_exit() -> None:
+    if _session is not None:
+        _session.close()

outwrite-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: outwrite
+Version: 0.1.0a1
+Summary: Python logging and a live status line, across threads and processes.
+License-Expression: MIT
+Project-URL: Source, https://github.com/ariel-m-s/outwrite
+Project-URL: Issues, https://github.com/ariel-m-s/outwrite/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<15,>=14
+Dynamic: license-file
+
+# Outwrite
+
+**Standard Python logging and one live status line, across threads and processes.**
+
+Outwrite connects Python's logging module to [Rich](https://github.com/Textualize/rich)
+and relays worker output to one renderer in the parent process. Use your existing
+processes and ordinary loggers. No queue management in application code.
+
+This is an early alpha. APIs may change; it is not production-certified.
+Python 3.11+ is required. Rich is the only runtime dependency.
+
+## Installation
+
+The first release is a prerelease:
+
+```sh
+python -m pip install outwrite==0.1.0a1
+```
+
+Or use `python -m pip install --pre outwrite` to allow the latest prerelease.
+These commands become available once the release is published to PyPI.
+
+To install from a local checkout:
+
+```sh
+python -m pip install .
+```
+
+## One process
+
+```python
+import logging
+from outwrite import setup_output, status
+
+logger = logging.getLogger("my_app")
+
+with setup_output(logger=logger) as output:
+    logger.info("Starting")
+    status.update("Processing files")
+    # Do some work.
+    status.clear()
+    logger.info("Done")
+```
+
+## Worker processes
+
+Pass the connection returned by the parent to each worker. Call the **same**
+setup function inside each worker:
+
+```python
+import logging
+import multiprocessing as mp
+import signal
+from outwrite import setup_output, status
+
+logger = logging.getLogger("my_app")
+
+def work(output, stop):
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    setup_output(output)
+    logger.info("Worker started")
+    for index in range(10):
+        if stop.is_set():
+            break
+        status.update(f"Processing file {index + 1}")
+        stop.wait(0.1)
+
+if __name__ == "__main__":
+    ctx = mp.get_context("spawn")
+    stop = ctx.Event()
+    with setup_output(logger=logger, mp_context=ctx) as output:
+        process = ctx.Process(target=work, args=(output, stop))
+        process.start()
+        try:
+            process.join()
+        finally:
+            stop.set()
+            process.join()
+```
+
+Always join workers and logging threads **inside** the parent context. On exit,
+Outwrite drains queued messages, clears the status, and releases its resources.
+Exit cleanup is also registered as a fallback; it does not stop or join workers
+for you. Forced process termination can lose messages or damage multiprocessing
+queues, so prefer a cooperative worker stop in real applications.
+
+See [the runnable example](https://github.com/ariel-m-s/outwrite/blob/main/examples/multiprocessing_demo.py).
+
+## API
+
+- `setup_output(logger=logger, level=logging.INFO, show_status=True, mp_context=ctx)`
+  starts parent output and returns an `OutputConnection` context handle.
+- `setup_output(output)` connects a worker. The parent's logger name and status
+  setting are carried by the connection; keyword options are for parent setup.
+- `status.update(text)` replaces the status line. `None` or `""` clears it.
+- `status.clear()` clears the line without ending the session.
+
+Status calls are safe from threads. Only one session and one status line are
+active per process; concurrent writers replace the same line. Status calls before
+setup or after parent cleanup raise `RuntimeError`.
+
+The console uses stderr. Status is automatically disabled outside terminals;
+logs still appear. `show_status=False` disables only status, and `level` controls
+only the Rich console handler. Use integer logging levels, such as `logging.DEBUG`.
+
+## Logging behavior
+
+Only the selected **named logger** and its propagating descendants are routed.
+The root logger and unrelated loggers are not configured. Child loggers with
+their own handlers or `propagate=False` retain their normal logging behavior.
+
+Existing handlers on the selected logger also receive records in the parent.
+For example, attach a standard `logging.FileHandler` before setup to retain file
+logging. Outwrite does not close your handlers. It adds a Rich console handler,
+so remove an existing console handler yourself if you do not want duplicate
+console output. The logger's original handlers, level, and propagation are
+restored when the parent context exits.
+
+Records pass through standard `QueueHandler` preparation: exception tracebacks
+become message text. Extra record attributes must be picklable. Cross-process
+delivery is asynchronous; use a cooperative worker shutdown and join workers to
+flush their messages. Ordering between different producers is not guaranteed.
+
+The default queue context is `spawn`. If using `forkserver`, pass that same
+context to setup and use it to create processes. `fork` is deliberately unsupported
+because the parent has an active rendering thread. Do not send a connection to
+an already-running pool; pass it when creating workers or through a pool initializer.
+
+Rendering failures are reported to stderr and raised when the parent context
+exits. Standard logging handlers retain their usual error-reporting behavior.
+No arbitrary stdout/stderr capture is performed.
+
+## Why not just Rich?
+
+Rich already supplies the columns, colors, links, and live display. Outwrite adds
+the connection between existing worker processes, standard logging, and one live
+status line. It is not a new renderer, process pool, or progress-bar framework.
+
+## Development
+
+```sh
+python -m pip install -e .
+python examples/multiprocessing_demo.py
+python -m pip install build
+python -m build
+```
+
+No persisted test suite is included in this initial iteration. Add regression
+tests before a production release, particularly for process shutdown and terminal
+cleanup.
+
+The initial wheel was verified on macOS ARM64 with Python 3.13.7 and 3.14.0,
+including spawn/forkserver workers and real-terminal Ctrl+C cleanup. Python
+3.11/3.12 and other operating systems have not yet been runtime-tested.
+
+## License
+
+MIT. The initial implementation adapts output coordination developed in Firefly,
+with its author's permission.
+
+## Publishing
+
+Maintainers use PyPI Trusted Publishing; no permanent upload token is stored in
+GitHub. The GitHub environment `pypi` requires approval before publication.
+
+1. Update the version in `pyproject.toml`, and commit and push the change.
+2. Create a GitHub release with a matching tag, such as `v0.1.0a1`.
+   Mark alpha/beta/RC versions as prereleases.
+3. Review the build job and approve the `pypi` environment deployment.
+4. Verify the uploaded version on PyPI and install it in a fresh environment.
+
+The workflow builds and validates the distributions before publishing. Release
+files cannot be replaced on PyPI; use a new version to correct a release.
+The initial pending publisher must be configured on PyPI for repository
+`ariel-m-s/outwrite`, workflow `publish.yml`, and environment `pypi`.

outwrite-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,8 @@
+outwrite/__init__.py,sha256=1vRhIi9AY8osy8im5EkW-_wXLMIRLDMywcOwD8pdY2k,186
+outwrite/_output.py,sha256=qROH-hVEwYA8fOs9O1jm0Sb74a1mQLUB6DZLTdpceZA,7915
+outwrite/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+outwrite-0.1.0a1.dist-info/licenses/LICENSE,sha256=lvOeGnZ0uumCPeZQu6CMF2Du-icaGTP-thzU2mXnJHE,1078
+outwrite-0.1.0a1.dist-info/METADATA,sha256=Fxi_SDeaPGYgBHMyXzl2EdJOwXvrZfAD_05zFC-f7JU,7485
+outwrite-0.1.0a1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+outwrite-0.1.0a1.dist-info/top_level.txt,sha256=45EdQ0LvxHSyiibXsxkslDl8Z3kHQZMSOFlOuS6ah8M,9
+outwrite-0.1.0a1.dist-info/RECORD,,

outwrite-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

outwrite-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Outwrite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outwrite-0.1.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+outwrite