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])[source]

Bases: object

Write module findings to a log file.

Parameters:
write()[source]

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()[source]

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

_write(text: str)[source]

Generalised log entry writer.

Parameters:

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

_write_dangerous(module: module.Module)[source]

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)[source]

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)[source]

Bases: object

Private wrapper class for all logging templates.

class badsnakes.libs.logger._LogTemplateBase(module_name: str)[source]

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)[source]

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[source]

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)[source]

Bases: _LogTemplateBase

Constant node class specific logging template class.

entry(node: containers.Constant) str[source]

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)[source]

Bases: _LogTemplateBase

Assignment node class specific logging template class.

entry(node: containers.Assign) str[source]

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)[source]

Bases: _LogTemplateBase

Attribute node class specific logging template class.

entry(node: containers.Attribute) str[source]

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)[source]

Bases: _LogTemplateBase

Call node class specific logging template class.

entry(node: containers.Call) str[source]

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)[source]

Bases: _LogTemplateBase

CodeText node class specific logging template class.

entry(node: containers.CodeText) str[source]

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)[source]

Bases: _LogTemplateBase

Constant node class specific logging template class.

entry(node: containers.Constant) str[source]

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)[source]

Bases: _LogTemplateBase

FunctionDef node class specific logging template class.

entry(node: containers.FunctionDef) str[source]

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)[source]

Bases: _LogTemplateBase

FunctionDef node class specific logging template class.

entry(node: containers.Import) str[source]

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