Logging classes and functions

class dysh.log.HistoricalBase

Bases: ABC

Abstract base class to manage history and comments metadata.

Attributes:

comments

Get the comment strings.

history

Get the history strings.

Methods

add_comment(comment[, add_time])	Add one or more comments to the class metadata.
add_history(history[, add_time])	Add one or more history entries to the class metadata
merge_commentary(other)	Merge the history and comments from another HistoricalBase instance.

add_comment(comment: str | Strlist, add_time: bool = False) → None

Add one or more comments to the class metadata.

Parameters:

commentstr or list of str or _HeaderCommentaryCards

The comment(s) to add

add_time: bool

If True, prepend the date and time the history was added

Returns:

None.

add_history(history: str | Strlist, add_time: bool = False) → None

Add one or more history entries to the class metadata

Parameters:

historystr or list of str or _HeaderCommentaryCards

The history card(s) to add

add_time: bool

If True, prepend the date and time the history was added.

Returns:

None.

property comments: Strlist

Get the comment strings. These are typically converted to FITS COMMENT cards by the derived class. Duplicate comments are removed. Comment strings are cleaned of non-ASCII and non-printable characters that are invalid in FITS Cards

Returns:

list

The list of string comments

property history: Strlist

Get the history strings. These are typically converted to FITS HISTORY cards by the derived class. Duplicate entries are removed. History strings are cleaned of non-ASCII and non-printable characters that are invalid in FITS Cards

Returns:

list

The list of string history

merge_commentary(other: object) → None

Merge the history and comments from another HistoricalBase instance. The history and comments are added to this instance and duplicates are removed.

Parameters:

other~log.HistoricalBase

An class instance that has history and comment attributes.

Returns:

None

dysh.log.dysh_date()

A date formatted for dysh log messages: ‘%Y-%m-%dT%H:%M:%S%z’

dysh.log.format_dysh_log_record(record: LogRecord) → str

Function to format a LogRecord into a string suitable for a FITS history card. This function is intended for records of a dysh class method invocation and is used by log_call_to_history()

Parameters:

recordlogging.LogRecord

The LogRecord to convert. It will have some special purpose added attributes

Returns:

str

The history string

dysh.log.init_console_log(level)

dysh.log.init_global_log(global_log_path: Path | None = None, rotate_bytes: int = 10000000, backups: int = 5, level: str | int = 'INFO') → Path

dysh.log.init_instance_log(instance_log_dir: Path = PosixPath('.'), instance_log_file: Path | None = None, level: str | int = 'INFO') → Path

dysh.log.init_logging(verbosity: int | None = None, path: Path | None = None, quiet: bool = False)

Initialize logging. Can be used, e.g., to change the verbosity level inside a script/shell.

Parameters:

verbosityint | None, optional

Verbosity level, 0 (ERRORs only) through 3 (DEBUG). The default is None.

pathPath | None, optional

An output path for the log messages. The default is None.

quietbool, optional

Quiet mode or not. The default is False.

Returns:

None.

Raises:

ValueError

If verbosity is not 0 to 3.

dysh.log.log_call_to_history(func: Callable)

Decorator to log a class method call to the class’s _history attribute. If the class has no such attribute, the function is still called but no logging takes place.

Parameters:

funcmethod

The class method.

Returns:

Any

The result of the method call

dysh.log.log_call_to_result(func: Callable)

Decorator to log a class method call to the method’s resultant class’s _history attribute. If the resultant class has no such attribute, the function is still called but no logging takes place.

Parameters:

funcmethod

The class method.

Returns:

Any

The result of the method call

dysh.log.log_function_call(log_level: str = 'info')

Decorator to log a function call

Parameters:

log_levelstr

The logging level to use for logging. One of [‘CRITICAL’, ‘FATAL’, ‘ERROR’, ‘WARN’, ‘WARNING’, ‘INFO’, ‘DEBUG’, ‘NOTSET’]. Case-insensitive. Default: ‘info’

Returns:

inner_decoratorAny

Whatever the function returns.