Logger API

This is the API reference for the heat_helper logger. You can find usage examples here.

hh.enable_logging

enable_logging(
    level: int | str = "INFO",
    *,
    fmt: str | None = None,
    stream: TextIO | None = None,
) -> logging.Logger

Turns on heat_helper's log output.

By default heat_helper shows warnings only, and without any formatting. Call this to see what the cleaning and matching functions are doing - particularly useful when using errors='coerce', where values are silently converted to None - and to get level and module names on every line.

Only the 'heat_helper' logger is touched; the root logger and any logging your own application has configured are left alone. Calling this function more than once replaces the previous handler rather than adding a second, so it is safe to re-run in a notebook cell.

Parameters:

Name	Type	Description	Default
`level`	`optional`	Minimum level to show. Accepts a name ('DEBUG', 'INFO', 'WARNING') or a `logging` constant. Defaults to 'INFO', which shows one summary line per Series operation. Use 'DEBUG' to see per-value decisions. Note that DEBUG output includes the data values themselves, which may be personal data.	`'INFO'`
`fmt`	`optional`	A `logging` format string. Defaults to '%(levelname)s %(name)s: %(message)s'.	`None`
`stream`	`optional`	Where to write. Defaults to `sys.stderr`, matching standard logging behaviour.	`None`

Raises:

Type	Description
`ValueError`	Raised if `level` is not a valid logging level name.

Returns:

Type	Description
`Logger`	The configured 'heat_helper' logger, so it can be tuned further.

hh.disable_logging

disable_logging() -> logging.Logger

Turns heat_helper's log output back off.

Removes the handler added by enable_logging() and restores the default behaviour, where records propagate to whatever logging the host application has configured. Safe to call when logging was never enabled.

Note this restores the default, which is not complete silence: INFO and DEBUG stop, but warnings remain visible, because they report problems that can corrupt a HEAT upload. To silence the package entirely, add a null handler yourself:

import logging
logging.getLogger("heat_helper").addHandler(logging.NullHandler())

Returns:

Type	Description
`Logger`	The 'heat_helper' logger.