Module: logger.py — badsnakes - v0.2.0 Documentation

# Module: logger.py

Purpose:

  This module provides the file-based reporting functionality for the project. Terminal-based reporting is handled by the `badsnakes.libs.reporter` module.

  Each `_LogTemplate*` class is responsible for the formatting of each AST node class. Whereas the primary caller `Logger` class controls the file creation and writing functionalities.

Platform:

  Linux/Windows | Python 3.10+

Developer:

  J Berendt

Email:

  development@s3dev.uk

Comments:

  n/a

Example:

  Create a log file for a given module, or modules:

      >>> from badsnakes import Module
      >>> from badsnakes.libs.logger import Logger

      # Analyse a Python module.
      >>> m = Module(path='/path/to/millworker.py')
      >>> m.analyse()

      # Create the log file.
      >>> l = Logger(path='/path/to/millworker.log', modules=[m])
      >>> l.write()

class badsnakes.libs.logger.Logger(path: str, modules: list[module.Module] | tuple[module.Module])

  Bases: `object`

  Write module findings to a log file.

  Parameters:

    - path (str) – Full path to the log file to be created.

    - modules (list[module.Module] | tuple[module.Module]) – A list or tuple containing `badsnakes.libs.module.Module` objects containing findings to be written to a log file.

  write()

    Write log entries for all modules.

    Logic:

      For each module passed on instantiation, create a logging template parent-class, based on the module’s name.

      Suspect findings are written first, followed by dangerous findings.

  _setup()

    Create the new log file, if it does not already exist.

  _write(text: str)

    Generalised log entry writer.

    Parameters:

      text (str) – Delimited text string to be written to the log.

  _write_dangerous(module: module.Module)

    Write a module’s dangerous findings to the log file.

    Parameters:

      module (module.Module) – Module for which the log entries are to be written.

    Logic:

      For each AST node class, obtain the associated log template sub-class from `_LogTemplates`, using the node class’ `.name` property.

      Using the AST-specific log template, write the dangerous findings to the log file created on logger instantiation.

  _write_suspect(module: module.Module)

    Write a module’s suspect findings to the log file.

    Parameters:

      module (module.Module) – Module for which the log entries are to be written.

    Logic:

      For each AST node class, obtain the associated log template sub-class from `_LogTemplates`, using the node class’ `.name` property.

      Using the AST-specific log template, write the suspect findings to the log file created on logger instantiation.

class badsnakes.libs.logger._LogTemplates(module_name: str)

  Bases: `object`

  Private wrapper class for all logging templates.

class badsnakes.libs.logger._LogTemplateBase(module_name: str)

  Bases: `object`

  Private template logging base class.

  This class provides the `_populate()` method to the sub-classes, which is used to build the log entry.

  Parameters:

    module_name (str) – Name of the module being logged. This name is written to the ‘module’ field of the log file.

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateArguments(module_name: str)

  Bases: `_LogTemplateBase`

  `Constant` node class specific logging template class.

  entry(node: containers.Constant) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.Constant) – A `badsnakes.libs.containers.Constant` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateAssignment(module_name: str)

  Bases: `_LogTemplateBase`

  `Assignment` node class specific logging template class.

  entry(node: containers.Assign) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.Assign) – A `badsnakes.libs.containers.Assign` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateAttribute(module_name: str)

  Bases: `_LogTemplateBase`

  `Attribute` node class specific logging template class.

  entry(node: containers.Attribute) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.Attribute) – A `badsnakes.libs.containers.Attribute` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateCall(module_name: str)

  Bases: `_LogTemplateBase`

  `Call` node class specific logging template class.

  entry(node: containers.Call) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.Call) – A `badsnakes.libs.containers.Call` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateCodeText(module_name: str)

  Bases: `_LogTemplateBase`

  `CodeText` node class specific logging template class.

  entry(node: containers.CodeText) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.CodeText) – A `badsnakes.libs.containers.CodeText` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateConstant(module_name: str)

  Bases: `_LogTemplateBase`

  `Constant` node class specific logging template class.

  entry(node: containers.Constant) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.Constant) – A `badsnakes.libs.containers.Constant` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateFunctionDef(module_name: str)

  Bases: `_LogTemplateBase`

  `FunctionDef` node class specific logging template class.

  entry(node: containers.FunctionDef) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.FunctionDef) – A `badsnakes.libs.containers.FunctionDef` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

class badsnakes.libs.logger._LogTemplateImport(module_name: str)

  Bases: `_LogTemplateBase`

  `FunctionDef` node class specific logging template class.

  entry(node: containers.Import) → str

    Generate a node-specific log entry.

    Parameters:

      node (containers.Import) – A `badsnakes.libs.containers.Import` object containing the values from which the log entry is derived.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  _populate(node: object, text: str, title: str = None) → str

    Generate a node-specific log entry.

    Parameters:

      - node (object) – AST node container from which the severity and line numbers are obtained.

      - text (str) – Text to be written to the ‘text’ field of the log file.

      - title (str, optional) – Title to be written to the ‘title’ field of the log file. If provided, this argument overrides the `_TITLE` attribute of the node-specific logging class. Defaults to None.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str

  entry_longstring(node: object)

    Generate an entry for a long string.

    Parameters:

      node (object) – AST node container from which the severity and line numbers are obtained.

    Note

    Long strings are truncated to the leading and trailing 25 characters to preserve brevity.

    Returns:

      The complete, formatted entry to be written to the log file.

    Return type:

      str