pylogfile API

pylogfile.base module

Provides the basic functionality of the package. Most of the functionality of this module is contained in the LogPile and LogEntry classes.

class pylogfile.base.DummyMutex

Bases: object

class pylogfile.base.LogEntry(level: int = 0, message: str = '', detail: str = '')

Bases: object

Defines a single entry in the log. Contains log messages, levels, additional detail, etc.

level

Log level int code

Type:

int

timestamp

Time at which log was created

Type:

datetime

message

Primary log message

Type:

str

detail

Additional log message detail

Type:

str

default_format = LogFormat(show_detail=False, use_color=True, default_color={'main': '\x1b[37m\x1b[49m', 'bold': '\x1b[94m', 'quiet': '\x1b[90m', 'alt': '\x1b[33m', 'label': '\x1b[32m'}, color_overrides={5: {'label': '\x1b[37m'}, 10: {'label': '\x1b[90m'}, 20: {}, 30: {'label': '\x1b[33m'}, 40: {'label': '\x1b[91m'}, 50: {'label': '\x1b[31m'}, -25: {'label': '\x1b[36m'}, -30: {'label': '\x1b[36m'}}, detail_indent='\t ', strip_newlines=True)
get_dict() → dict

Returns the contents of the log as a dictionary.

Returns:

Dictionary containing log entry data

Return type:

(dict)

get_json() → str

Returns the class as a JSON string.

Returns:

All class data in JSON form

Return type:

(str)

get_level_str() → str

Converts the log’s level to a string

Returns:

Log level represented as a string.

Return type:

(str)

init_dict(data_dict: dict) → bool

Initializes a provided dictionary with the data from the LogEntry. Used when preparing to save logs to file.

Parameters:

data_dict (dict) – Dictionary to populate with data

Returns:

Success status in converting class contents to dict

Return type:

(bool)

matches_sort(orders: SortConditions) → bool

Checks if the entry matches the conditions specified by the SortConditions ‘orders’. Returns true if they match and false if they don’t. NOTE: Does not check index, that is only valid in a LogPile context.

Parameters:

orders (SortConditions) – Sort conditions to check against

Returns:

True if matched sort conditions

Return type:

(bool)

str(str_fmt: LogFormat = None) → str

Represent the log entry as a formatted string suitable for printing.

Parameters:

str_fmt (LogFormat) – Format specification

Returns:

String representation of class

Return type:

(str)

class pylogfile.base.LogFormat(show_detail: bool = False, use_color: bool = True, default_color: dict = <factory>, color_overrides: dict = <factory>, detail_indent: str = '\t ', strip_newlines: bool = True)

Bases: object

Class used to describe the cosmetic formatting of LogEntries printed to standard output.

color_overrides: dict
default_color: dict
detail_indent: str = '\t '
show_detail: bool = False
strip_newlines: bool = True
use_color: bool = True
class pylogfile.base.LogPile(filename: str = '', autosave: bool = False, str_fmt: LogFormat = None, use_mutex: bool = True)

Bases: object

Organizes a collection of LogEntries and creates new ones. All functions are thread safe.

use_mutex allows the user to specify that the mutex should or should not be used. Because mutexes are not serializable, if the LogPile object will need to be deepcopied, use_mutex should be set to false.

terminal_output_enable

Enables or disables automatically printing each log to the standard output.

Type:

bool

terminal_level

Log level, at or above, which logs will print to the standard output.

Type:

int

autosave_enable

Tracks if autosave is enabled

Type:

bool

filename

Name to autosave

Type:

str

autosave_period_s

Time between autosaves in seconds

Type:

float

autosave_level

Minimum log level to save.

Type:

int

autosave_format

File format for autosave. Options are ‘format-json’ and ‘format-txt’.

Type:

str

str_fmt

LogFormat settings

Type:

LogFormat

logs

List of LogEntries contained in the LogPile.

Type:

list

log_mutex

Used to protect the logs attribute and allow the creation of logs across multiple threads.

Type:

Lock

run_mutex

Used to protect

Type:

Lock

JSON = 'format-json'
TXT = 'format-txt'
add_log(level: int, message: str, detail: str = '')

Adds a log.

Parameters:

  • level (int) – Level int code at which to add log

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

begin_autosave()
critical(message: str, detail: str = '')

Logs data at CRITICAL level.

Parameters:

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

debug(message: str, detail: str = '')

Logs data at DEBUG level.

Parameters:

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

error(message: str, detail: str = '')

Logs data at ERROR level.

Parameters:

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

info(message: str, detail: str = '')

Logs data at INFO level.

Parameters:

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

load_hdf(read_filename: str, clear_previous: bool = True)

Reads logs from an HDF5 file.

Parameters:

  • read_filename (str) – Name of file to read

  • clear_previous (bool) – Sets whether previous logs contained in the LogPile shouold be erased before reading the file.

Returns:

Success status

Return type:

(bool)

load_json(read_filename: str, clear_previous: bool = True) → bool

Reads logs from a JSON file.

Parameters:

  • read_filename (str) – Name of file to read

  • clear_previous (bool) – Sets whether previous logs contained in the LogPile shouold be erased before reading the file.

Returns:

True if successfully read file

Return type:

(bool)

lowdebug(message: str, detail: str = '')

Logs data at LOWDEBUG level.

Parameters:

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

run_new_log(nl: LogEntry)

Runs a new log, processing any instructions therein. Typically this just entails printing the log, formatted, to standard output.

Parameters:

nl (LogEntry) – Log to run

Returns:

None

save_hdf(save_filename)

Saves all logs to an HDF5 file.

Parameters:

save_filename (str) – Name of file to save to

Returns:

None

save_json(save_filename: str)

Saves all log data to a JSON file.

Parameters:

save_filename (str) – filename to save

Returns:

None

save_txt()
set_enable_mutex(enabled: bool)
set_terminal_level(level_str: str)

Sets the terminal display level from a level name string.

Parameters:

level_str (str) – Level to set

Returns:

None

show_logs(min_level: int = 10, max_level: int = 50, max_number: int = None, from_beginning: bool = False, show_index: bool = True, sort_orders: SortConditions = None, str_fmt: LogFormat = None)

Prints to standard output the logs matching the specified conditions.

Parameters:

  • min_level (int) – Minimum logging level to display

  • max_level (int) – Maximum logging level to display

  • max_number (int) – Maximum number of logs to show

  • from_beginning (bool) – Show logs starting from beginning.

  • show_index (bool) – Show or hide the index of the log entry by each entry.

Returns:

None

to_dict()

Returns a dictionary representing the logs in the LogPile.

warning(message: str, detail: str = '')

Logs data at WARNING level.

Parameters:

  • message (str) – Message to add to log

  • detail (str) – Additional detail to add to log

Returns:

None

class pylogfile.base.SortConditions

Bases: object

Class used to define the conditions of a LogEntry sort request.

contains_and = []
contains_or = []
index_end = None
index_start = None
time_end = None
time_start = None
pylogfile.base.markdown(msg: str, str_fmt: LogFormat = None) → str

Applys Pylogfile markdown to a string. Pylogfile markdown uses a series of characters to change the color of the output text.

List of escape characters to alter text color:

  • > Temporarily change to bold

  • < Revert to previous color

  • >:n Temporariliy change to color ‘n’ (See list of ‘n’-codes below)

  • >> Permanently change to bold

  • >>:n Permanently change to color ‘n’ (See list of ‘n’-codes below)

>, <, Type character without color adjustment. So to get >>:3

to appear you’d type >>:3. Similarly, to type a lock character without setting or remove the lock, type >:L> or <:L<

List of escape characters used to lock markdown: (Case-sensitive) - @:LOCK Enables the lock, ignoring all markdown except @:UNLOCK - @:UNLOCK Disables the lock, re-enabling all markdown. To Preface either of these sequences with `` (ie. a single backslash) to interpret them as text rather than a lock character.

A backslash can be used to escape angle brackets and forgoe applying color adjustment. For example, “>” and “<” would render “>” and “<”, respectively once processed through pylogfile markdown. So as an example, to render “>>:3”, you would need to input “>>:3”.

List of ‘n’-codes: (Case insensitive)

  • 1 or m: Main

  • 2 or b: Bold

  • 3 or q: Quiet

  • 4 or a: Alt

  • 5 or l: Label

So for example, “>:3Test<” or “>:qTest<” would change the color to ‘Quiet’, print ‘Test’, and return to the original color.

Parameters:

  • msg (str) – String to process with pylogfile markdown.

  • str_fmt (LogFormat) – Optional formatting specification to apply

Returns:

Formatted text

Return type:

(str)

pylogfile.base.mdprint(x: str, flush: bool = False, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, end: str = '\n', str_fmt: LogFormat = None) → None

Calls print using markdown syntax.

Parameters:

  • x (str) – String to print. Unlike the standard print function, x must be a string.

  • flush (bool) – (Optional) Sets if output is flushed immediately. Default=False.

  • file – (Optional) file-like object to which the output should be written. Default is sys.stdout.

  • end (str) – (Optional) Defines what is printed at the end of the output. Default is newline.

  • str_fmt (LogFormat) – (Optional) Markdown format options.

Returns

None

pylogfile.base.str_to_level(lvl: str) → int

Converts a log level string to its associated int code.

Parameters:

lvl (str) – Log level string, case-insensitive

Returns:

The log level int code

Return type:

int

Subpackages