spacr.qt.logging_util
=====================

.. py:module:: spacr.qt.logging_util

.. autoapi-nested-parse::

   Qt-side extension of the package-scope logger.

   Delegates all file-handler configuration to :mod:`spacr.logging_util`
   and adds a :class:`QtLogHandler` that emits every formatted record
   over a Qt signal so widgets on the main thread can display them
   without cross-thread violations.

   Two sinks end up wired at ``spacr-qt`` startup:

   1. The rotating file handler at ``~/.spacr/logs/spacr.log``
      (installed by :mod:`spacr.logging_util`).
   2. The :class:`QtLogHandler` here — ConsolePanel connects to its
      ``record_ready(str, int)`` signal.

   Public API:
       setup_logging(...)   — call once early in ``launch()``.
       get_signal_handler() — the shared QtLogHandler instance.
       log_path()           — absolute path of the rotating log file.







Module Contents
---------------

.. py:function:: log_dir() -> pathlib.Path

   Return the folder where spacr log files live.

   Alias for :func:`spacr.logging_util.log_dir`.


.. py:function:: log_path() -> pathlib.Path

   Return the absolute path of the rotating log file.

   Alias for :func:`spacr.logging_util.log_path`.


.. py:class:: QtLogHandler(level: int = logging.INFO)

   Bases: :py:obj:`PySide6.QtCore.QObject`, :py:obj:`logging.Handler`


   A logging.Handler that emits every formatted record over a Qt
   signal so QWidget slots (running on the main thread) can display
   them without cross-thread violations.

   :ivar record_ready: signal ``(formatted_line, levelno)`` emitted
       once per record.


   .. py:attribute:: record_ready


   .. py:method:: emit(record: logging.LogRecord) -> None

      Format and re-emit ``record`` over :attr:`record_ready`.



.. py:function:: get_signal_handler() -> QtLogHandler

   Return the shared QtLogHandler. Instantiated on first access.


.. py:function:: setup_logging(level: int = logging.INFO, console_level: int = logging.INFO) -> None

   Install the file handler + the Qt signal handler on the root
   logger. Idempotent — safe to call more than once.

   :param level: minimum record level for the rotating file handler.
   :param console_level: minimum record level for the Qt signal handler
       (i.e. what ConsolePanel receives).


.. py:function:: get_logger(name: str = 'spacr.qt') -> logging.Logger

   Convenience wrapper — returns a child logger under ``spacr.qt``.

   :param name: logger name, defaults to ``"spacr.qt"``.


