Logging classes and functions

class dysh.log.DatestampFileHandler(filename, mode='w', encoding=None, delay=False)

Bases: FileHandler

Attributes:

name

Methods

acquire()	Acquire the I/O thread lock.
addFilter(filter)	Add the specified filter to this handler.
close()	Closes the stream.
createLock()	Acquire a thread lock for serializing access to the underlying I/O.
emit(record)	Emit a record.
filter(record)	Determine if a record is loggable by consulting all the filters.
flush()	Flushes the stream.
format(record)	Format the specified record.
handle(record)	Conditionally emit the specified logging record.
handleError(record)	Handle errors which occur during an emit() call.
release()	Release the I/O thread lock.
removeFilter(filter)	Remove the specified filter from this handler.
setFormatter(fmt)	Set the formatter for this handler.
setLevel(level)	Set the logging level of this handler.
setStream(stream)	Sets the StreamHandler's stream to the specified value, if it is different.

get_name
set_name

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

class dysh.log.StringHandler

Bases: StreamHandler

Attributes:

name

Methods

acquire()	Acquire the I/O thread lock.
addFilter(filter)	Add the specified filter to this handler.
close()	Tidy up any resources used by the handler.
createLock()	Acquire a thread lock for serializing access to the underlying I/O.
emit(record)	Emit a record.
filter(record)	Determine if a record is loggable by consulting all the filters.
flush()	Flushes the stream.
format(record)	Format the specified record.
handle(record)	Conditionally emit the specified logging record.
handleError(record)	Handle errors which occur during an emit() call.
release()	Release the I/O thread lock.
removeFilter(filter)	Remove the specified filter from this handler.
setFormatter(fmt)	Set the formatter for this handler.
setLevel(level)	Set the logging level of this handler.
setStream(stream)	Sets the StreamHandler's stream to the specified value, if it is different.

get_name
set_name

dysh.log.dysh_date()

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_logging(verbosity: int, level: int | None = None, path: Path | None = None, quiet=False)

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.