molclusters.log

log

Logging tools and configuration.

STATUS

Bases: Enum

Status code, can be OFF (0) or ON (1).

format_duration

format_duration(seconds: float) -> str

Format a duration for humans, e.g. 4.2s, 12m 03s or 1h 02m 03s.

Returns:

Type	Description
str	The formatted duration.

Source code in src/molclusters/log.py

def format_duration(seconds: float) -> str:
    """Format a duration for humans, e.g. ``4.2s``, ``12m 03s`` or ``1h 02m 03s``.

    Returns
    -------
    str
        The formatted duration.
    """
    if seconds < 60:
        return f"{seconds:.1f}s"
    minutes, secs = divmod(round(seconds), 60)
    if minutes < 60:
        return f"{minutes}m {secs:02d}s"
    hours, minutes = divmod(minutes, 60)
    return f"{hours}h {minutes:02d}m {secs:02d}s"

start_logging

start_logging(level: Literal['TRACE', 'DEBUG', 'INFO', 'SUCCESS', 'WARNING', 'ERROR', 'CRITICAL'] | int = 'INFO', *, filename: Path | str = Path('molclusters.log')) -> None

Start log handlers for the molclusters library.

Parameters:

Name	Type	Description	Default
level	Literal['TRACE', 'DEBUG', 'INFO', 'SUCCESS', 'WARNING', 'ERROR', 'CRITICAL'] | int	Log level to start the logger, by default "INFO"	'INFO'
filename	Path | str	The log file, by default "molclusters.log"; a serialized copy is written next to it with a .json suffix. Warnings from other packages (MDAnalysis) are logged as well.	Path('molclusters.log')

Source code in src/molclusters/log.py

def start_logging(
    level: Literal["TRACE", "DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL"]
    | int = "INFO",
    *,
    filename: Path | str = Path("molclusters.log"),
) -> None:
    """Start log handlers for the molclusters library.

    Parameters
    ----------
    level : Literal[ "TRACE", "DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL" ] | int, optional
        Log level to start the logger, by default "INFO"
    filename : Path | str, optional
        The log file, by default "molclusters.log"; a serialized copy is written
        next to it with a ``.json`` suffix. Warnings from other packages
        (MDAnalysis) are logged as well.
    """
    global LOG_STATUS

    if LOG_STATUS == STATUS.OFF:
        filename = Path(filename)

        logger.remove(0)
        # written through tqdm so a message doesn't break an active progress bar
        logger.add(
            lambda msg: tqdm.write(msg, end="", file=sys.stderr),
            level=level,
            format=_formatter(_TERMINAL_FORMAT),
            colorize=sys.stderr.isatty(),
            filter=_not_file_only,
        )
        logger.add(filename.with_suffix(".json"), serialize=True, level=level)
        logger.add(filename, level=level, format=_formatter(_FILE_FORMAT))
        _route_third_party_logs()

        logger.enable("molclusters")
        logger.info(f"MolClusters {version} | Logging to {filename.resolve()}")
        logger.info(
            f"Python {platform.python_version()}, MDAnalysis {mda.__version__}, "
            f"NumPy {np.__version__}, NetworkX {nx.__version__}, "
            f"pandas {pd.__version__}"
        )

        LOG_STATUS = STATUS.ON