[python source code]

logging

Helpers for logging.

LoggingLevels

Bases: CustomStrEnum

flowchart LR tm_devices.helpers.logging.LoggingLevels[LoggingLevels] tm_devices.helpers.enums.CustomStrEnum[CustomStrEnum] tm_devices.helpers.enums.CustomStrEnum --> tm_devices.helpers.logging.LoggingLevels click tm_devices.helpers.logging.LoggingLevels href "" "tm_devices.helpers.logging.LoggingLevels" click tm_devices.helpers.enums.CustomStrEnum href "" "tm_devices.helpers.enums.CustomStrEnum"

A class holding the valid logging levels supported.

CRITICAL class-attribute instance-attribute 

CRITICAL = 'CRITICAL'

An enum member representing the CRITICAL logging level.

DEBUG class-attribute instance-attribute 

DEBUG = 'DEBUG'

An enum member representing the DEBUG logging level.

ERROR class-attribute instance-attribute 

ERROR = 'ERROR'

An enum member representing the ERROR logging level.

INFO class-attribute instance-attribute 

INFO = 'INFO'

An enum member representing the INFO logging level.

NONE class-attribute instance-attribute 

NONE = 'NONE'

An enum member indicating no logging messages should be captured.

WARNING class-attribute instance-attribute 

WARNING = 'WARNING'

An enum member representing the WARNING logging level.

name property 

name: str

Return the name of the Enum member.

value property 

value: str

Return the value of the Enum member.

list_values classmethod 

list_values() -> list[str]

Return a list of all the values of the enum.

configure_logging 

configure_logging(
    *,
    log_console_level: str | LoggingLevels = INFO,
    log_file_level: str | LoggingLevels = DEBUG,
    log_file_directory: str | PathLike[str] | Path | None = None,
    log_file_name: str | None = None,
    log_colored_output: bool = False,
    log_pyvisa_messages: bool = False,
    log_uncaught_exceptions: bool = True
) -> Logger

Configure the logging for this package.

Note

After this function is called once, if it is called again, it will not perform any additional configuration. It will simply return the base logger for the package. This means that if logging is configured explicitly in Python code, then any configuration options set in the config file or environment variables will be ignored.

Important

This function will overwrite the sys.excepthook function in order to log uncaught exceptions if logging to a log file is enabled. The custom hook function used by this package will call sys.__excepthook__ after the custom code is run, so exceptions and tracebacks will still get printed to the console. If you have a custom exception hook function you need to use, you will need to overwrite the sys.excepthook function after this package’s logging is configured. To opt out of this behavior and keep Python’s default exception handling (which means exceptions will not be logged to the log file), set the log_uncaught_exceptions parameter to False.

Parameters:
  • log_console_level (str | LoggingLevels, default: INFO ) –

    The logging level to set for the console. Defaults to INFO. Set to LoggingLevels.NONE to disable all console logging/printouts except for certain warnings and exceptions.

  • log_file_level (str | LoggingLevels, default: DEBUG ) –

    The logging level to set for the file. Defaults to DEBUG. Set to LoggingLevels.NONE to disable logging to a file entirely.

  • log_file_directory (str | PathLike[str] | Path | None, default: None ) –

    The directory to save log files to. Defaults to “./logs” in the current working directory.

  • log_file_name (str | None, default: None ) –

    The name of the log file to save the logs to. Defaults to a timestamped name with the .log extension.

  • log_colored_output (bool, default: False ) –

    Whether to use colored output from the colorlog package for the console. Defaults to False.

  • log_pyvisa_messages (bool, default: False ) –

    Whether to include logs from the pyvisa package in the log file. The logging level used for these additional log entries will match log_file_level. Defaults to False.

  • log_uncaught_exceptions (bool, default: True ) –

    Whether to log uncaught exceptions to the log file with full tracebacks and reduce the traceback size of exceptions in the console. Defaults to True. Setting the log_file_level parameter to LoggingLevels.NONE will disable this feature regardless of the value of log_uncaught_exceptions.
Returns:
  • Logger –

    The base logger for the package, this base logger can also be accessed using logging.getLogger(tm_devices.PACKAGE_NAME).

disable_all_loggers 

disable_all_loggers(
    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "CRITICAL",
) -> Generator[None, None, None]

Temporarily disable all logging calls of severity ‘level’ and below within this context.

Examples:

>>> with disable_all_loggers():
...     logging.info("This is inside the context and will not be logged")

>>> logging.info("This is outside the context and will be logged")

>>> with disable_all_loggers(level="WARNING"):
...     logging.info("This will not be logged")
...     logging.warning("This will not be logged")
...     logging.error("This will be logged since its level is above WARNING")
Parameters:
  • level (Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'], default: 'CRITICAL' ) –

    The logging level under which all log messages will be suppressed.