fora.logger

Provides logging utilities.

Attributes

attr logger.state

logger.state: State = State()

The global logger state.

class logger.State

Global state for logging.

Attributes

attr indentation_level

indentation_level: int = 0

The current global indentation level.

class logger.IndentationContext

A context manager to modify the indentation level.

Functions

def logger.use_color()

def logger.use_color() -> bool:

Returns true if color should be used.

def logger.col()

def logger.col(color_code: str) -> str:

Returns the given argument only if color is enabled.

def logger.ellipsis()

def logger.ellipsis(s: str, width: int) -> str:

Shrinks the given string to width (including an ellipsis character).

Parameters

• s: The string.

• width: The maximum width.

Returns

• str: A modified string with at most width characters.

def logger.indent()

def logger.indent() -> IndentationContext:

Retruns a context manager that increases the indentation level.

def logger.indent_prefix()

def logger.indent_prefix() -> str:

Returns the indentation prefix for the current indentation level.

def logger.debug()

def logger.debug(msg: str) -> None:

Prints the given message only in debug mode.

def logger.debug_args()

def logger.debug_args(msg: str, args: dict[str, Any]) -> None:

Prints all given arguments when in debug mode.

def logger.print_indented()

def logger.print_indented(msg: str, **kwargs: Any) -> None:

Same as print(), but prefixes the message with the indentation prefix.

def logger.connection_init()

def logger.connection_init(connector: Any) -> None:

Prints connection initialization information.

def logger.connection_failed()

def logger.connection_failed(error_msg: str) -> None:

Signals that an error has occurred while establishing the connection.

def logger.connection_established()

def logger.connection_established() -> None:

Signals that the connection has been successfully established.

def logger.run_script()

def logger.run_script(script: str, name: Optional[str] = None) -> None:

Prints the script file and name that is being executed next.

def logger.print_operation_title()

def logger.print_operation_title(op: Any, title_color: str, end: str = '\n'
        ) -> None:

Prints the operation title and description.

def logger.print_operation_early()

def logger.print_operation_early(op: Any) -> None:

Prints the operation title and description before the final status is known.

def logger.decode_escape()

def logger.decode_escape(data: bytes, encoding: str = 'utf-8') -> str:

Tries to decode the given data with the given encoding, but replaces all non-decodeable and non-printable characters with backslash escape sequences.

Example:

>>> decode_escape(b'It is Wednesday\nmy dudes\r\n🐸\xff\0')
'It is Wednesday\\nMy Dudes\\r\\n🐸\\xff\\0'

Parameters

• content: The content that should be decoded and escaped.

• encoding: The encoding that should be tried. To preserve utf-8 symbols, use 'utf-8', to replace any non-ascii character with an escape sequence use 'ascii'.

Returns

• str: The decoded and escaped string.

def logger.diff()

def logger.diff(filename: str, old: Optional[bytes], new: Optional[bytes], 
                color: bool = True) -> list[str]:

Creates a diff between the old and new content of the given filename, that can be printed to the console. This function returns the diff output as an array of lines. The lines in the output array are not terminated by newlines.

If color is True, the diff is colored using ANSI escape sequences.

If you want to provide an alternative diffing function, beware that the input can theoretically contain any bytes and therefore should be decoded as utf-8 if possible, but non-decodeable or non-printable charaters should be replaced with human readable variants such as \x00, ^@ or similar represenations.

Your diffing function should still be able to work on the raw bytes representation, after you aquire the diff and before you apply colors, your output should be made printable with a function such as logger.decode_escape():

# First decode and escape
line = logger.decode_escape(byteline)
# Add coloring afterwards so ANSI escape sequences are not escaped

Parameters

• filename: The filename of the file that is being diffed.

• old: The old content, or None if the file didn't exist before.

• new: The new content, or None if the file was deleted.

• color: Whether the output should be colored (with ANSI color sequences).

Returns

• list[str]: The lines of the diff output. The individual lines will not have a terminating newline.

def logger.print_operation()

def logger.print_operation(op: Any, result: Any) -> None:

Prints the operation summary after it has finished execution.