Logging#

VneuroTK does not configure logging when imported. It uses Loguru, so records remain available to sinks that the host application has already configured, without VneuroTK deleting or replacing those sinks.

To add a VneuroTK-owned sink explicitly, call vneurotk.setup_logging("INFO").

setup_logging() is idempotent: another call replaces only the sink created by the previous call. Its sink is filtered to the vneurotk package. set_log_level("DEBUG") is a convenience API for configuring that VneuroTK sink; with no argument it reads VNTK_LOGGING_LEVEL and defaults to INFO.

MNE logging and Python warning filters are process-global, so VneuroTK leaves them unchanged by default. Applications that deliberately want VneuroTK to configure them can pass mne_level="ERROR" and suppress_mne_naming_warnings=True to setup_logging().

API#

vneurotk._log.setup_logging(level='INFO', sink=None, *, colorize=True, mne_level=None, suppress_mne_naming_warnings=False)#

Configure an idempotent, VneuroTK-owned logging sink.

The sink is filtered to records from the vneurotk package. Existing Loguru sinks belong to the host application and are never removed or reconfigured. Repeated calls replace only the sink previously created by this function.

MNE integration is separately opt-in because both MNE’s log level and Python warning filters are process-global. Pass mne_level and/or suppress_mne_naming_warnings=True only when the application wants VneuroTK to own those settings.

Parameters:
levelstr

Minimum level for the VneuroTK-owned sink: "DEBUG", "INFO", "WARNING", "ERROR", or "CRITICAL". Default "INFO".

sinkfile-like or None

Output sink passed to loguru.Logger.add(). Defaults to sys.stderr.

colorizebool

Enable ANSI colour codes on the VneuroTK-owned sink. Default True.

mne_levelstr or None

When provided, explicitly set MNE-Python’s process-global log level. None (the default) leaves MNE unchanged.

suppress_mne_naming_warningsbool

Explicitly install a process-global warning filter for MNE channel naming-convention warnings. Default False leaves warning filters unchanged.

Parameters:

  • level (str)

  • sink (Any)

  • colorize (bool)

  • mne_level (str | None)

  • suppress_mne_naming_warnings (bool)

Return type:

None

vneurotk._log.set_log_level(verbose=None)#

Set the level of the VneuroTK-owned sink.

This function does not alter host Loguru sinks or MNE settings. Loguru sinks configured by the host may independently choose to receive VneuroTK records.

Parameters:
verbosestr or None

Log level: "DEBUG", "INFO", "WARNING", "ERROR", or "CRITICAL". If None, read VNTK_LOGGING_LEVEL and fall back to "INFO" when it is unset.

Parameters:

verbose (str | None)

Return type:

None

Examples

>>> import vneurotk as vtk
>>> vtk.set_log_level("DEBUG")
>>> vtk.set_log_level()  # from VNTK_LOGGING_LEVEL or INFO