pds4_tools.utils.logging module

Classes

PDS4Logger(*args, **kwargs)

Custom PDS4 Logger, for its internal log use.

PDS4StreamHandler(name[, level])

Custom StreamHandler that has a name and a is_quiet attributes.

PDS4SilentHandler(name)

Custom StreamHandler that saves emitted records to records attribute.

PDS4Formatter([fmt, datefmt, style])

Custom formatter that varies format according to log level.

Functions

logger_init()

Initializes or obtains the logger for PDS4 tools and its handlers.

set_loglevel(level)

Enables log messages from the PDS4 tools logger to propagate to ancestor loggers based on the log level.

Details

pds4_tools.set_loglevel()

An alias of set_loglevel().

class PDS4Logger(*args, **kwargs)[source]

Bases: logging.Logger, object

Custom PDS4 Logger, for its internal log use.

Additional features over standard logger:

  • Get handlers by name

  • Has quiet or loud methods

  • Set maximum number of repetitions for a logging message via e.g. .log(... max_repeats=n)

  • Set custom line terminator on per message basis for all stream handlers via e.g. .log(..., end='str')

property stream_handlers
Returns
logging.StreamHandler or subclasses

Stream handlers bound to this logger.

get_handler(handler_name)[source]

Obtain handler by name.

Parameters
handler_namestr or unicode

The name of the handler.

Returns
PDS4StreamHandler or PDS4SilentHandler

Handler for this logger, matching the handler_name.

quiet(handler_name='stdout_handler')[source]

Sets a handler to log only errors.

Parameters
handler_namestr or unicode, optional

Handler name to select. Defaults to stdout handler.

Returns
None
loud(handler_name='stdout_handler')[source]

Sets a handler to log warnings and above.

Parameters
handler_namestr or unicode, optional

Handler name to select. Defaults to stdout handler.

Returns
None
is_quiet(handler_name='stdout_handler')[source]

Obtains whether a handler is quiet.

Parameters
handler_namestr or unicode, optional

Handler name to select. Defaults to stdout handler.

Returns
bool

True if the logger is quiet, i.e. logs only errors; false otherwise.

set_terminators(ends=None)[source]

Sets line terminator for all stream handlers.

Parameters
endsstr, unicode or list[str or unicode]

The line terminator (same for all stream handlers) or sequence of terminators. Sequence order must be same as order of stream handlers in stream_handlers attribute.

Returns
None
setLevel(level, handler_name=None)[source]

Set log level for entire logger or a specific handler.

Parameters
levelint or str

Level to set for logger or handler. See Python documentation on logger levels for details.

handler_namestr or unicode, optional

Handler name to select. Defaults to the entire logger.

Returns
None
class PDS4StreamHandler(name, level=10)[source]

Bases: logging.StreamHandler

Custom StreamHandler that has a name and a is_quiet attributes.

emit(record)[source]

Emit a record.

Subclassed to allow handler.terminator to be used as the line terminator rather than hardcode the newline character on any supported Python version. This is a standard feature on Python >= 3.2, but not available earlier.

property name
Returns
str or unicode

Name of the handler.

property is_quiet
Returns
bool

True if handler is quiet, False otherwise.

set_level(level)[source]

Set handler log level.

Convenience method for setLevel.

Parameters
levelint or str

Level to set for handler. See Python documentation on logger levels for details.

get_level()[source]

Get handler log level.

Convenience method for the level attribute.

Returns
int

Level for handler. See Python documentation on logger levels for details.

setLevel(level)[source]

Set handler log level.

Overloads logging.StreamHandler.setLevel to automatically set whether logger is quiet or loud.

Parameters
levelint or str

Level to set for handler. See Python documentation on logger levels for details.

class PDS4SilentHandler(name)[source]

Bases: pds4_tools.utils.logging.PDS4StreamHandler

Custom StreamHandler that saves emitted records to records attribute.

Able to print out previously emitted records via to_string.

name
Returns
str or unicode

Name of the handler.

is_quiet
Returns
bool

True if handler is quiet, False otherwise.

get_level()

Get handler log level.

Convenience method for the level attribute.

Returns
int

Level for handler. See Python documentation on logger levels for details.

set_level(level)

Set handler log level.

Convenience method for setLevel.

Parameters
levelint or str

Level to set for handler. See Python documentation on logger levels for details.

setLevel(level)

Set handler log level.

Overloads logging.StreamHandler.setLevel to automatically set whether logger is quiet or loud.

Parameters
levelint or str

Level to set for handler. See Python documentation on logger levels for details.

emit(record)[source]

Saves emitted record.

Emitted record is shallow copied, then message is modified as described. First, we insert the current line terminator, as otherwise this information would be lost. Second, if the current or prior record contains a stand alone carriage-return character, we save only the final state of the stream output as it would be if printed to a terminal. Generally carriage return is likely only to be used to overwrite old messages on the same line (e.g. how a download progress bar works); saving each message would pollute the message queue, and potentially take a huge amount of memory.

Parameters
recordlogger.LogRecord

Record to emit.

Returns
None
begin_recording()[source]

Used in conjunction with get_recording. Records emitted after this method is called will be returned by get_recording.

Returns
None
get_recording(reset=True)[source]

Obtains records since begin_recording was called as a joined string.

Parameters
resetbool, optional

If True, begins a new recording from now on. If False, recording from previous point continues. Defaults to True.

Returns
str or unicode

A string containing the messages that were emitted since begin_recording was called.

Raises
RuntimeError

Raised if begin_recording was not called prior to calling this method.

to_string(start_i=0, end_i=None)[source]

Output emitted records as a joined string.

Parameters
start_iint, optional

Index of first record to include. Defaults to 0 (include records from the beginning).

end_iint, optional

Index of last record to include. Defaults to None (include records until the end).

Returns
str or unicode

A string containing the messages in the records that were previously emitted.

class PDS4Formatter(fmt=None, datefmt=None, style='%')[source]

Bases: logging.Formatter

Custom formatter that varies format according to log level.

format(record)[source]
Parameters
recordlogger.LogRecord

The record to format.

Returns
str or unicode

The formatted record string.

logger_init()[source]

Initializes or obtains the logger for PDS4 tools and its handlers.

Returns
PDS4Logger

The global logger for all pds4 tools.

set_loglevel(level)[source]

Enables log messages from the PDS4 tools logger to propagate to ancestor loggers based on the log level.

By default log messages are not propagated. To receive info+ log messages, one would typically set_loglevel('info'), while setting pds4_read(..., quiet=True) to avoid duplicate information to stdout.

Parameters
levelint or str

Level to set for handler. See Python documentation on logger levels for details.

Returns
None