spacr.logging_util

Package-scope Python logging setup for spacr.

Central configuration for every spacr subsystem — core pipelines, I/O, measure, utilities, and the Qt GUI all funnel through the same rotating file handler at ~/.spacr/logs/spacr.log.

Two ways to opt in:

• Automatic — the Qt GUI calls setup_logging() at launch, so once you run spacr-qt the log file is populated for the life of the session.

• Manual — for headless scripts and notebooks:

  from spacr.logging_util import setup_logging, get_logger
  setup_logging()                # once, at program start
  LOG = get_logger(__name__)     # in every module that logs
  LOG.info("started")
  

The log level can be overridden by SPACR_LOG_LEVEL in the env (DEBUG, INFO, WARNING, …). enable_debug() and disable_debug() are convenience toggles for interactive use.

Third-party libraries that spam INFO records during a spacr pipeline (torch, cellpose, matplotlib, PIL, urllib3, botocore, tensorflow, asyncio) are pinned to WARNING so the log stays useful. Add more to QUIET_LOGGERS if a new dependency starts spamming.

Public API:

setup_logging(level=INFO, log_file=None) — call once early. get_logger(name) — module-scoped logger. enable_debug() — crank spacr.* to DEBUG. disable_debug() — revert to session level. log_dir() — folder holding the log. log_path() — absolute log file path.

Module Contents

spacr.logging_util.DEFAULT_LOG_FILENAME = 'spacr.log'

spacr.logging_util.MAX_BYTES = 5242880

spacr.logging_util.BACKUP_COUNT = 3

spacr.logging_util.FILE_FORMAT = '%(asctime)s [%(levelname)s] %(name)s:%(filename)s:%(lineno)d — %(message)s'

spacr.logging_util.STREAM_FORMAT = '%(levelname)s %(name)s: %(message)s'

spacr.logging_util.QUIET_LOGGERS: tuple[str, Ellipsis] = ('PIL', 'matplotlib', 'urllib3', 'asyncio', 'torch', 'torchvision', 'cellpose', 'tensorflow',...

spacr.logging_util.log_dir() → pathlib.Path

Return the folder where spacr log files live.

Returns:

~/.spacr/logs — created if it does not exist.

spacr.logging_util.log_path() → pathlib.Path

Return the absolute path of the rotating log file.

Uses whatever was passed to setup_logging() last, or the default under log_dir() when never set.

spacr.logging_util.setup_logging(level: int | None = None, log_file: pathlib.Path | None = None, stream: bool = False, quiet: Iterable[str] = QUIET_LOGGERS) → pathlib.Path

Install the rotating file handler on the root logger.

Idempotent — subsequent calls only re-apply the level, they don’t stack additional handlers. Honours the SPACR_LOG_LEVEL environment variable when level is not given.

Parameters:

• level – minimum record level for the log file. Defaults to SPACR_LOG_LEVEL env var (any of DEBUG/INFO/…) or logging.INFO.

• log_file – override for where the file lands. Defaults to log_path().

• stream – also attach a StreamHandler to stderr — handy for headless / CI runs where the log file isn’t inspected.

• quiet – iterable of logger names to pin at WARNING. Defaults to QUIET_LOGGERS.

Returns:

the resolved log-file path.

spacr.logging_util.get_logger(name: str) → logging.Logger

Return a spacr-scoped logging.Logger.

Idiomatic usage from any module:

from spacr.logging_util import get_logger
LOG = get_logger(__name__)

Parameters:

name – logger name — typically __name__ so the log stream shows which module the record came from.

spacr.logging_util.enable_debug() → None

Crank every spacr.* logger to DEBUG.

Useful when debugging interactively:

>>> from spacr.logging_util import enable_debug
>>> enable_debug()

Third-party loggers listed in QUIET_LOGGERS are left at WARNING to keep the log readable.

spacr.logging_util.disable_debug() → None

Revert every spacr.* logger to the level chosen at setup.

Inverse of enable_debug().